Overview

The DockerPush native step pushes a Docker Image to a Docker registry.


  • Currently, only Docker registries in Artifactory are supported.
  • DockerBuild and DockerPush steps must be assigned to the same affinityGroup to share state. If they are not, the output of DockerBuild will not be available to DockerPush. For more information on affinityGroup see Pipelines Steps.


YAML Schema

The YAML schema for DockerPush native step is as follows:

pipelines: 
  - name:   <string>
    steps:
      - name: <string>
        type: DockerPush
        configuration:
          #inherits all the tags from bash; https://www.jfrog.com/confluence/display/JFROG/Bash
          affinityGroup:        <string>
          targetRepository:     <string>        # required. Must be a local repository. Virtual repositories are not supported.
          forceXrayScan:        <boolean>       # default false
          failOnScan:           <boolean>       # default true
          autoPublishBuildInfo: <boolean>       # default false

          integrations:
            - name:             <artifactory integration>  # required
          inputSteps:
            - name:             <DockerBuild step>         # required
          outputResources:
            - name: 		    <Image resource>           # optional
            - name: 		    <BuildInfo resource>       # required if autoPublishBuildInfo is true

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

Tags

name 

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

type 

Must be DockerPush 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
affinityGroup Must specify an affinity group string that is the same as specified in a prior DockerBuild step.Optional
integrations Must specify an Artifactory Integration.Required
inputSteps Must specify the named DockerBuild step in the same affinity group.Required
outputResources

May specify an Image resource. If one is specified, the imageTag property of that resource will be updated with the dockerImageTag of the preceding DockerBuild step.

Must specify a BuildInfo resource if autoPublishBuildInfo is set to true. If JFROG_CLI_BUILD_NAME or JFROG_CLI_BUILD_NUMBER is set as an environment variable for the pipeline or the inputDockerBuild step, that name and/or number is used for the output BuildInfo. Otherwise, the defaultbuildName and buildNumber are $pipeline_name and $run_number respectively .

Optional

May be 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
targetRepository

The name of the Docker repository in Artifactory.

Must be a local repository. Virtual repositories are not supported.

Required
forceXrayScan

When true, forces a scan of the pushed image by JFrog Xray.

Default is false.

Optional
failOnScan

When set to true, and when the Xray Policy Rule Fail Build checkbox is checked, a failed Xray scan will result in a failure of the step.

Default is true.

Optional
autoPublishBuildInfo

When set to true, publishes build info with the Docker image.

Default is false.

Optional


execution

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

TagDescription of usageRequired/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 DockerPush step to push a Docker image.

Push Image to Artifactory

Pushes the image created by the DockerBuild input step to Artifactory. Does not trigger a scan.

# 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_repo1
    type: GitRepo
    configuration:
      gitProvider: {{ .Values.gitIntegration }}                      
      path: {{ .Values.gitRepositoryPath }}    
      branches:
        include: master

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

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

pipelines:
  - name: app_dev_pipeline
    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

Affinity Group

This extends one of the DockerBuild examples, pushing that image to Artifactory. Note that an affinity group has been specified in both steps.

pipelines:
  - name: demo_pipeline
    steps:
      - name: bld_image
        type: DockerBuild
        configuration:
          affinityGroup: dockerGroup
          dockerFileLocation: .
          dockerFileName: Dockerfile
          dockerImageName: docker.artprod.mycompany.com/gosvc   # replace with your fully qualified Docker registry/image name
          dockerImageTag: ${run_number}
          dockerOptions: --build-arg build_number_env_variable=${run_number}          
          inputResources:
            - name: gosvc_app
          integrations:
            - name: MyArtifactory

      - name: dockerPushStep
        type: DockerPush
        configuration:
          affinityGroup: dockerGroup
          targetRepository: dockerRepo
          inputSteps:
            - name: bld_image
          outputResources:
            - name: outputBuildInfo
          integrations:
            - name: MyArtifactory

Publish Build Info, Trigger Xray Scan, Update Output Image Resource

In this, publishing build info, triggering an Xray scan, and updating an output Image resource has been added to the previous example.

pipelines:
  - name: demo_pipeline
    steps:
      - name: bld_image
        type: DockerBuild
        configuration:
          affinityGroup: dockerGroup
          dockerFileLocation: .
          dockerFileName: Dockerfile
          dockerImageName: docker.artprod.mycompany.com/gosvc   # replace with your fully qualified Docker registry/image name
          dockerImageTag: ${run_number}
          dockerOptions: --build-arg build_number_env_variable=${run_number}          
          inputResources:
            - name: gosvc_app
          integrations:
            - name: MyArtifactory

      - name: dockerPushStep
        type: DockerPush
        configuration:
          affinityGroup: dockerGroup
          targetRepository: dockerRepo
          autoPublishBuildInfo: true
          forceXrayScan: true
          inputSteps:
            - name: bld_image
          outputResources:
            - name: outputBuildInfo
            - name: outputImage
          integrations:
            - name: MyArtifactory

How it Works

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

  • jfrog rt use (to set the current default Artifactory configuration to the one set up for the integration in integrations)
  • restore_run_files (copy the build information saved from the DockerBuild step)
  • jfrog rt docker-push (push the image to Artifactory)
  • jfrog rt build-publish (if autoPublishBuildInfo is true, publish the build info)
  • write_output (if autoPublishBuildInfo is true, update the BuildInfo buildName and buildNumber)
  • write_output (if there is an output Image resource, update the Image imageTag)
  • jfrog rt build-scan (if forceXrayScan is true, trigger a scan)
  • add_run_files (save/update the build information in the run state for later publish steps)