Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >

Search





Overview

The PromoteBuild native step promotes a BuildInfo and moves or copies the related artifacts from one Artifactory repository to another. 


This step requires a BuildInfo resource as an input to successfully execute.
Page Contents


YAML Schema

The YAML schema for PromoteBuild native step is as follows:

PromoteBuild
pipelines:
  - name:   <string>
    steps:
      - name: <string>
        type: PromoteBuild
        configuration:
          #inherits all the tags from bash; https://www.jfrog.com/confluence/display/JFROG/Bash
          targetRepository:      <string>
          includeDependencies:   <boolean>    # default false
          status:				 <string>  
          comment:				 <string>
		  copy:					 <boolean>

          inputResources:
            - name:         <BuildInfo resource>     # required
              trigger: false
          outputResources:
            - name:         <BuildInfo resource>     # required

        execution:
          onStart:
            - echo "Preparing for work..."
          onSuccess:
            - echo "Job well done!"
          onFailure:
            - echo "uh oh, something went wrong"
          onComplete: #always
            - echo "Cleaning up some stuff"

Tags

name 

An alphanumeric string (underscores are permitted) that identifies the step.

type 

Must be PromoteBuild for this step type.

configuration

Specifies all configuration selections for the step's execution environment. This step inherits the Bash/PowerShell step configuration tags, including these pertinent tags:

Tag

Description of usage

Required/Optional
inputResources Must specify a named BuildInfo resource whose buildName and buildNumber properties identify the build to promote .Required
outputResources Must specify a named BuildInfo resource to map to the promoted build. The BuildInfo will be updated with the buildName and buildNumber of the input BuildInfo resource, and its targetRepo with the value of targetRepository. Required


In addition, these tags can be defined to support the step's native operation:

All native steps derive from the Bash step. This means that all steps share the same base set of tags from Bash, while native steps have their own additional tags as well that support the step's particular function. So it's important to be familiar with the Bash step definition, since it's the core of the definition of all other steps.

Tag

Description of usage

Required/Optional
targetRepositoryThe name of the repository in Artifactory to promote the build to.Required
includeDependencies

When set to true, promotion will include the build dependencies.

Defaults to false.

Optional
statusName of the status to promote the build to.Optional
commentComment to include for the promotion.Optional
copy

When set to true, copies the artifacts to the targetRepository vs moving them to the targetRepository.

Defaults to false.

Optional

execution

Declares collections of shell command sequences to perform for pre- and post-execution phases:

Tag

Description of usage

Required/Optional
onStartCommands to execute in advance of the native operationOptional
onSuccessCommands to execute on successful completionOptional
onFailureCommands to execute on failed completionOptional
onCompleteCommands to execute on any completionOptional


The actions performed for the onExecute phase are inherent to this step type and may not be overridden.


Examples

The following examples show how to configure a PromoteBuild step.

Promote Build to Artifactory

Promotes a build specified by an input BuildInfo to an Artifactory repository named docker-prod-local. In this example, trigger is set as false on the input resource so that the step will not be automatically triggered.

PromoteBuild
# This config file is templatized so that it can be easily customized. Values can be provided with a values.yml file.
template: true   # required for local templates
valuesFilePath: ./values.yml

resources:
  - name: app_repo
    type: GitRepo
    configuration:
      gitProvider: {{ .Values.gitIntegration }}                      
      path: {{ .Values.gitRepositoryPath }}    
      branches:
        include: master

  - name: app_buildinfo
    type: BuildInfo
    configuration:
      sourceArtifactory: {{ .Values.artifactoryIntegration }}

  - name: app_promoted_buildinfo
    type: BuildInfo
    configuration:
      sourceArtifactory: {{ .Values.artifactoryIntegration }}

pipelines:
  - name: app_dev_pipeline_su204
    steps:
      - name: app_build
        type: DockerBuild
        configuration:
          affinityGroup: docker_group
          dockerFileLocation: .
          dockerFileName: Dockerfile
          dockerImageName: {{ .Values.artifactoryUrl }}/{{ .Values.sourceRepository }}/{{ .Values.imageName }}  
          dockerImageTag: ${run_number}
          inputResources:
            - name: app_repo
          integrations:
            - name: {{ .Values.artifactoryIntegration }}         
            
      - name: app_push
        type: DockerPush
        configuration:
          affinityGroup: docker_group
          targetRepository: {{ .Values.sourceRepository }}
          integrations:
            - name: {{ .Values.artifactoryIntegration }}                            
          inputSteps:
            - name: app_build

      - name: publish_app_build
        type: PublishBuildInfo
        configuration:
          affinityGroup: docker_group
          inputSteps:
            - name: app_push
          outputResources:
            - name: app_buildinfo
            
      - name: xrayScanStep
        type: XrayScan
        configuration:
          inputResources:
            - name: app_buildinfo   

  - name: app_prod_pipeline_su204
    steps:
      - name: app_promote_build
        type: PromoteBuild
        configuration:
          targetRepository: {{ .Values.prodRepository }}
          inputResources:
            - name: app_buildinfo
              trigger: false
          outputResources:
            - name: app_promoted_buildinfo

      - name: app_deploy
        type: Bash
        configuration:
          integrations:
            - name: {{ .Values.artifactoryIntegration }}
          inputResources:
            - name: app_promoted_buildinfo
        execution:
          onStart:
            - jfrog rt docker-pull {{ .Values.artifactoryUrl }}/{{ .Values.prodRepository }}/{{ .Values.imageName }}:$res_app_promoted_buildinfo_buildNumber {{ .Values.prodRepository }}
            #- jfrog rt dl prod-go-local/app
            #- ls -latr
          onExecute:
            - docker run {{ .Values.artifactoryUrl }}/{{ .Values.prodRepository }}/{{ .Values.imageName }}:$res_app_promoted_buildinfo_buildNumber

Promote Build with Status and Comment

Promotes the build with a status and comment.

PromoteBuild
pipelines: 
  - name: promoteBuildPipeline
    steps:
      - name: promoteBuildStep
        type: PromoteBuild
        configuration:
          targetRepository: my-promoted-builds
          status: TEST
          comment: "Promoted by run number ${run_number}."
          integrations:
            - name: artifactory_integration
          inputResources:
            - name: inputBuildInfo
              trigger: false
          outputResources:
            - name: outputBuildInfo

Promote Build and Copy

In this example, when the build is promoted, it is copied so that a copy remains in the previous repository and the dependencies are copied as well as the build.

PromoteBuild
pipelines: 
  - name: promoteBuildPipeline
    steps:
      - name: promoteBuildStep
        type: PromoteBuild
        configuration:
          targetRepository: my-promoted-builds
          includeDependencies: true
          copy: true
          integrations:
            - name: artifactory_integration
          inputResources:
            - name: inputBuildInfo
              trigger: false
          outputResources:
            - name: outputBuildInfo

How it Works

When you use the PromoteBuild native step in a pipeline, it performs the following functions in the background:

  • jfrog rt config (configure the JFrog CLI with the credentials in the BuildInfo input)
  • jfrog rt build-promote
  • write_output (update the output BuildInfo resource)
  • No labels
Copyright © 2021 JFrog Ltd.