PromoteBuild

JFrog Pipelines Documentation
ft:sourceType
Paligo

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

Note

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

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
          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 pertinenttags:

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:

Note

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

targetRepository

The 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

status

Name of the status to promote the build to.

Optional

comment

Comment 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

onStart

Commands to execute in advance of the native operation

Optional

onSuccess

Commands to execute on successful completion

Optional

onFailure

Commands to execute on failed completion

Optional

onComplete

Commands to execute on any completion

Optional

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)