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

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  w hen 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 publish build info or trigger a scan.

This example is not a complete pipeline. A DockerBuild step must be part of the same pipeline.

pipelines: 
  - name: dockerPushPipeline
    steps:
      - name: dockerPushStep
        type: DockerPush
        configuration:
          targetRepository: dockerRepo
          inputSteps:
            - name: docker_build
          integrations:
            - name: artifactory_integration

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)