Buildkite

Authentication

For Buildkite, you can use OIDC, project, or user access tokens for authenticating your build with Depot. Because Buildkite supports the OIDC flow, we recommend using that for the best experience.

OIDC token

The easiest option is to use a Buildkite OIDC token as authentication for depot build. Our CLI supports authentication via OIDC by default in Buildkite when you have a trust relationship configured for your project.

Project token

You can inject a project access token into the pipeline for depot CLI authentication. Project tokens are tied to a specific project in your organization and not a user.

User access token

You can inject a user access token into the pipeline for depot CLI authentication. User tokens are tied to a specific user and not a project. Therefore, it can be used to build all projects across all organizations that the user can access.

Configuration

To build a Docker image from Buildkite, you must either configure an OIDC trust relationship for your project or set the DEPOT_TOKEN environment variable via a Buildkite environment hook.

This guide also assumes that you are defining a pipeline.yml configuration file located in a .buildkite directory at the root of your repository. See the Buildkite documentation for more information on how to configure your pipeline this way.

To build a Docker image with Depot inside of your Buildkite pipeline, you must first install the depot CLI, and then you can run depot build.

steps:
  - label: 'Build image with Depot'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'depot build .'

Examples

Build multi-platform images natively without emulation

This example shows how you can use the --platform flag to build a multi-platform image for Intel and Arm architectures natively without emulation.

steps:
  - label: 'Build image with Depot'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'depot build --platform linux/amd64,linux/arm64 .'

Build and push to Docker Hub

This example assumes you have set the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN environment variables as part of the environment hook and you have the docker CLI installed in your Buildkite agent.

We then install the depot CLI to be used directly in the pipeline. Then, docker login is invoked with the environment variables for DOCKERHUB_USERNAME and DOCKERHUB_TOKEN for the authentication context of the build to push to the registry.

steps:
  - label: 'Build image with Depot and push to Docker Hub'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'docker login --username $DOCKERHUB_USERNAME --password $DOCKERHUB_TOKEN'
      - 'depot build -t <your-registry>:<your-tag> --push .'

Build and push to Amazon ECR

This example installs the depot and aws CLIs to be used directly. Then, aws ecr get-login-password is piped into docker login for the authentication context of the build to push to the registry.

steps:
  - label: 'Build image with Depot and push to Docker Hub'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'curl https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip'
      - 'unzip awscliv2.zip'
      - './aws/install'
      - 'aws ecr get-login-password --region <your-ecr-region> | docker login --username AWS --password-stdin <your-ecr-registry>'
      - 'depot build -t <your-ecr-registry>:<your-tag> --push .'

Build and load the image back for testing

You can use the --load flag to download the built container image into the workflow.

steps:
  - label: 'Build image with Depot'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'depot build --load .'

Build, push, and load the image back in one command

You can simultaneously push the built image to a registry and load it back into the CI job by using the --load and --push flag together.

steps:
  - label: 'Build image with Depot'
    command:
      - 'curl -L https://depot.dev/install-cli.sh | DEPOT_INSTALL_DIR=/usr/local/bin sh'
      - 'depot build -t <your-registry> --push --load .'