YAML Schema
The YAML schema for DockerBuild native step is as follows:
pipelines:
- name: <string>
steps:
- name: <string>
type: DockerBuild
configuration:
#inherits from bash
affinityGroup: <string>
dockerFileLocation: <string>
dockerFileName: <string>
dockerImageName: <string>
dockerImageTag: <string>
dockerOptions: <string>
integrations:
- name: <artifactory integration> # required
inputResources:
- name: <GitRepo resource> # required, git repository containing your Dockerfile
- name: <Image resource> # optional base image
- name: <FileSpec resource> # optional
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 DockerBuild 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 subsequent DockerPush step. | Optional |
inputResources | Must specify:
Optionally, you may also specify: | Required/Optional |
In addition, these tags can be defined to support the step's native operation:
Tag | Description of usage | Required/Optional |
|---|---|---|
| Directory containing the Dockerfile, which is the file that has Docker build configuration. This file is also used as the context for the Docker build. The path provided should be relative to the root of the input GitRepo repository. If no location is provided, the default is the root of the GitRepo repository. | Required |
| Name of the Dockerfile. | Required |
| The name of the Docker image to create. This can be set using environment variables or triggering a run using parameters. | Required |
| The tag for the Docker image to create. This can be set using environment variables or triggering a run using parameters. | Required |
dockerOptions
| Additional options for the docker build command. | Optional |
Examples
The following examples use a GoLang Git repository represented by a GitRepo resource named gosvc_app to create a Docker image that is published to Artifactory. They assume that an Artifactory integration named MyArtifactory has been created, and that the Artifactory instance has a Docker repository mapped to docker.artprod.company.
- These examples require an Artifactory Integration and a GitHub Integration.
- The Pipelines DSL for a similar example is available in this repository in the JFrog GitHub account.
- For a full tutorial, see Pipeline Example: Docker Build and Push.
The following resources declarations support these examples. Not all of these resources are used in all examples.
Resources
resources:
# Application source repository
- name: gosvc_app
type: GitRepo
configuration:
gitProvider: myGithub
path: myuser/myrepo # replace with your repository name
branches:
include: master
# Docker image in an Artifactory repository
- name: base_image
type: Image
configuration:
registry: myArtifactory
sourceRepository: docker-local # replace with your repository name
imageName: docker.artprod.mycompany.com/baseimage
imageTag: latest
autoPull: true
# Files in an Artifactory repository
- name: icon_files
type: FileSpec
configuration:
sourceArtifactory: myArtifactory
pattern: my-local-repo/all-my-images/
target: icons/
Build a Docker image from a source repository
This example builds a Docker image to a Docker registry in Artifactory. The tag for the image is set to the pipeline's run number.
pipelines:
- name: demo_pipeline
steps:
- name: bld_image
type: DockerBuild
configuration:
dockerFileLocation: .
dockerFileName: Dockerfile
dockerImageName: docker.artprod.mycompany.com/gosvc # replace with your fully qualified Docker registry/image name
dockerImageTag: ${run_number}
inputResources:
- name: gosvc_app
integrations:
- name: MyArtifactory
Build a Docker image with dockerOptions
This example demonstrates use of the dockerOptions tag to set the build-arg option for the Docker command. An environment variable named build_number_env_variable is dynamically set to the pipeline's run number. The example assumes the environment variable is used in the Dockerfile commands.
pipelines:
- name: demo_pipeline
steps:
- name: bld_image
type: DockerBuild
configuration:
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
Build a Docker image with a private base image
This example builds a Docker image that relies on a private base image stored in an Artifactory Docker repository.
pipelines:
- name: demo_pipeline
steps:
- name: bld_image
type: DockerBuild
configuration:
dockerFileLocation: .
dockerFileName: Dockerfile
dockerImageName: docker.artprod.mycompany.com/gosvc # replace with your fully qualified Docker registry/image name
dockerImageTag: ${run_number}
inputResources:
- name: gosvc_app
- name: base_image
integrations:
- name: MyArtifactory
Build a Docker image with files outside the current path
This example demonstrates building a Docker image that includes files outside of the current path. It pulls icon files stored in an Artifactory repository for integration art named my-local-repo. It is assumed that the Dockerfile has a command that will include the files in /icons into the image.
pipelines:
- name: demo_pipeline
steps:
- name: bld_image
type: DockerBuild
configuration:
dockerFileLocation: .
dockerFileName: Dockerfile
dockerImageName: docker.artprod.mycompany.com/gosvc # replace with your fully qualified Docker registry/image name
dockerImageTag: ${run_number}
inputResources:
- name: gosvc_app
- name: icon_files
integrations:
- name: MyArtifactory
How it Works
When you use the DockerBuild native step in a pipeline, it performs the following functions in the background:
- cp (if there is a FileSpec input, copy those files to the root of the cloned GitRepo input)
- docker build
- add_run_variables (add several variables that are later used when pushing the Docker image or publishing build info)
- jfrog rt build-collect-env (collect environment information to be later published as part of build info)
- add_run_files (save information collected for build info)
