ECR Buildkite Plugin

A Buildkite plugin to login to an ECR repository before running a build step.

This will use standard AWS credentials available in the environment, or as an instance role or task role as available. These must be granted appropriate permissions for login to succeed and for push and pull to operate.

Example

This will perform a docker login to your ECR registries prior to running your step commands.

steps:
  - command: ./run_build.sh
    plugins:
      - ecr#v2.10.0: ~

If you want to log in to ECR on another account:

steps:
  - command: ./run_build.sh
    plugins:
      - ecr#v2.10.0:
          account-ids: "0015615400570"
          region: "ap-southeast-2"

If you need to assume a role to perform that login:

steps:
  - command: ./run_build.sh
    plugins:
      - ecr#v2.10.0:
          account-ids: "0015615400570"
          region: "ap-southeast-2"
          assume_role:
            role_arn: "arn:aws:iam::0015615400570:role/demo"

Using ECR Credential Helper

You can use the Amazon ECR credential helper instead of the traditional AWS CLI login methods. This provides automatic credential management and better performance through caching:

steps:
  - command: ./run_build.sh
    plugins:
      - ecr#v2.10.0:
          credential-helper: true

The credential helper works with any ECR registries you have access to, without needing to specify account IDs (though you can still specify them for explicit control):

steps:
  - command: ./run_build.sh
    plugins:
      - ecr#v2.10.0:
          credential-helper: true
          account-ids:
            - "123456789012"
            - "public.ecr.aws"

Options

login (optional)

Whether to login to your account’s ECR. Defaults to true. Set to false to disable ECR authentication.

credential-helper (optional)

Use the Amazon ECR credential helper instead of AWS CLI ECR login methods.

Requires the amazon-ecr-credential-helper binary to be installed and available in PATH.

account-ids (optional)

Either a string, or a list of strings with AWS account IDs that correspond to the Amazon ECR registries that you want to log in to. Make sure to quote these if they start with a 0.

If not specified, the plugin automatically uses your current AWS account ID (obtained via aws sts get-caller-identity).

You can use the literal public.ecr.aws as a value to authenticate against the AWS ECR Public, which hosts publicly available container images. This is useful when you need to push to or pull from public ECR repositories. Note that public ECR authentication always uses the us-east-1 region regardless of your configured region.

:warning: If you are using the Amazon ECR Credential Helper in your Docker configuration it is possible you have to add https:// to your account IDs to prevent an error (see the corresponding bug report for more information).

no-include-email (optional)

Obsolete if using AWS CLI version 1.17.10 or newer.

Add --no-include-email to ecr get-login. Required for Docker 17.06+, but needs aws-cli 1.11.91+.

region (optional)

Set a specific region for ECR, defaults to AWS_DEFAULT_REGION on the agent, or us-east-1 if none specified.

retries (optional)

Retries login after a delay N times. Defaults to 0.

assume-role (optional)

Updates AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN environment variables.

Assume an AWS IAM role before ECR login. Supports role-arn and duration-seconds (optional) per the associated AWS CLI command.

profile (optional)

Requires AWS CLI version 1.17.10 or greater.

Use a different AWS profile from the default during ECR login.

Developing

Use docker to run the Plugin Tester:

docker run --rm -ti -v "${PWD}":/plugin buildkite/plugin-tester:latest

License

MIT (see LICENSE)