A Buildkite plugin to build, tag, and push Docker images to Amazon ECR.
The following pipeline builds the default ./Dockerfile
and pushes it to a pre-existing ECR repository my-repo
:
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
ecr-name: my-repo
An alternate Dockerfile may be specified:
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
dockerfile: path/to/final.Dockerfile
ecr-name: my-repo
Build-time variables are supported, either with an explicit value, or without one to propagate an environment variable from the pipeline step:
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
args:
- BUILDKITE_BUILD_NUMBER # propagate environment variable
branch-args:
- BRANCH_TYPE=branch # explicit value
default-args:
- BRANCH_TYPE=default # explicit value
ecr-name: my-repo
All images are tagged with their corresponding $BUILDKITE_BUILD_NUMBER
.
Images built from the default branch are automatically tagged with latest
.
Additional tags may be listed:
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.3.0:
branch-tags:
- branch-$BUILDKITE_BUILD_NUMBER
default-tags:
# - latest
- default-$BUILDKITE_BUILD_NUMBER
ecr-name: my-repo
tags:
# - $BUILDKITE_BUILD_NUMBER
- any-$BUILDKITE_BUILD_NUMBER
If you're working with immutable image tags,
you can disable the latest
tag with the add-latest-tag
property:
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
add-latest-tag: false
ecr-name: my-repo
More complex branch workflows can be achieved by using multiple pipeline steps with differing branches
:
steps:
- branches: '!dev !prod'
plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
args: BRANCH_TYPE=branch
ecr-name: my-repo
tags: branch-$BUILDKITE_BUILD_NUMBER
- branches: dev
plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
args: BRANCH_TYPE=dev
ecr-name: my-repo
tags: dev-$BUILDKITE_BUILD_NUMBER
- branches: prod
plugins:
- seek-oss/docker-ecr-publish#v2.4.0:
args: BRANCH_TYPE=prod
ecr-name: my-repo
tags: prod-$BUILDKITE_BUILD_NUMBER
Additional docker build
arguments can be passed via the additional-build-args
setting:
steps:
- command: 'echo amaze'
env:
DOCKER_BUILDKIT: '1'
plugins:
- seek-oss/docker-ecr-publish#v2.3.0:
additional-build-args: '--progress=plain --ssh= default=\$SSH_AUTH_SOCK'
- docker#v3.5.0
This plugin can be used in combination with the Create ECR plugin to fully manage an ECR application repository within one pipeline step:
steps:
- plugins:
- seek-oss/create-ecr#v1.1.2:
name: my-repo
- seek-oss/docker-ecr-publish#v2.3.0:
ecr-name: my-repo
This plugin can be used in combination with the Docker ECR Cache plugin to reuse a base image across pipeline steps:
steps:
- command: npm test
plugins:
- seek-oss/docker-ecr-cache#v1.7.0:
ecr-name: my-cache
target: deps
- docker#v3.5.0:
volumes:
- /workdir/node_modules
- plugins:
- seek-oss/docker-ecr-cache#v1.7.0:
ecr-name: my-cache
target: deps
- seek-oss/docker-ecr-publish#v2.3.0:
cache-from: ecr:https://my-cache # defaults to latest tag
ecr-name: my-repo
We can target registries in other accounts and region(s), provided the current IAM user/role has the ability to auth against said account/registry:
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.3.0:
account_id: '12345678910'
region: eu-west-1
ecr-name: my-repo
steps:
- plugins:
- seek-oss/docker-ecr-publish#v2.1.0:
account_id: '12345678910'
regions:
- eu-west-1
- us-west-2
ecr-name: my-repo
-
args
(optional, array|string)Build args to provide to all builds. These are listed before the branch-specific
branch-args
anddefault-args
properties in the resultingdocker build
command.Sensitive arguments should be propagated as an environment variable (
MY_ARG
instead ofMY_ARG=blah
), so that they are not checked into your source control and then logged to Buildkite output by this plugin. -
add-latest-tag
(optional, boolean)Whether to add a
latest
tag to default branch builds.Default:
true
-
additional-build-args
(optional, string)Allows specifying additional arguments directly to the
docker build
command. -
branch-args
(optional, array|string)Build args to provide to non-default branch builds.
-
branch-tags
(optional, array|string)Tags to push on non-default branch builds.
-
build-context
(optional, string)The Docker build context. Valid values are as per the API
Default:
.
-
cache-from
(optional, array|string)Images for Docker to use as cache sources, e.g. a base or dependency image.
Use standard Docker image notation (e.g.
debian:jessie
,myregistry.local:5000/testing/test-image
), or theecr:https://cache-repo:tag
shorthand to point to an ECR repository in the current AWS account. -
default-args
(optional, array|string)Build args to provide to default branch builds.
-
default-tags
(optional, array|string)Tags to push on default branch builds.
Default:
latest
(non-removable) -
dockerfile
(optional, string)Local path to a custom Dockerfile.
Default:
Dockerfile
-
ecr-name
(required, string)Name of the ECR repository.
-
account_id
(optional, string)Account ID for ECR registry, defaults to output of
aws sts get-caller-identity
e.g. current account ID. -
region
(optional, array|string)Region the ECR registry is in, defaults to
$AWS_DEFAULT_REGION
and theneu-west-1
if not set. -
regions
(optional, array|string)Same as
region
. Both properties are optional, and they cannot be set at the same time. -
tags
(optional, array|string)Tags to push on all builds.
Default:
$BUILDKITE_BUILD_NUMBER
(non-removable) -
target
(optional, string)When building a Dockerfile with multiple build stages, target can be used to specify an intermediate build stage by name as the final stage for the resulting image. This corresponds to the Docker CLI
--target
parameter. -
save-digest-as-metadata
(optional, string)Specify a Buildkite metadata variable to save the Docker image digest to, e.g.
save-digest-as-metadata: runtime-image-digest
. -
driver
(optional, string, one ofbuildkit
,legacy
)Default value
legacy
Specify a Buildkite driver to use for building the image, e.g.
driver: buildkit
. -
progress-output
(optional, string, one ofplain
,tty
,auto
)Only takes effect if
driver: buildkit
Default valueplain
Specify the progress output format, e.g.
progress-output: tty
. -
disable-cache-metadata
(optional, string)Only takes effect if
driver: buildkit
Defaultfalse
Recommendation is to keep it
false
. Docker buildkit uses cached layers from a previously built image and listed incache-from
property. This greatly reduces time taken to build an image. Turning cache metadata off might significantly increase build time. e.g.disable-cache-metadata: true
.
MIT (see LICENSE)