CircleCI

Authentication

For CircleCI, you can use OIDC, project, or user access tokens for authenticating your build with Depot. We recommend OIDC tokens for the best experience, as they work automatically without provisioning a static access token.

OIDC token

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

Project token

You can set the DEPOT_TOKEN environment variable to a project access token in your CircleCI environment variable settings. Project tokens are tied to a specific project in your organization and not a user.

User access token

You can also set the DEPOT_TOKEN environment variable to a user access token in your CircleCI environment variable settings. 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 has access.

Configuration

To build a Docker image from CircleCI, you must set the DEPOT_TOKEN environment variable in your project settings. This is done through the UI for your project.

CircleCI has two executor types that allow you to build Docker images. The machine executor runs your job on the entire VM with docker pre-installed. The docker executor runs your job in a container. Depot can be used in either executor type.

Using the CircleCI machine executor

To install depot and run a Docker image build in CircleCI, add the following to your config.yml file:

version: 2.1
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build with Depot
          command: |
            depot build .

Using the CircleCI docker executor

If you would prefer to use the docker executor, you can use the following configuration:

version: 2.1
 
jobs:
  build:
    docker:
      - image: cimg/node:lts
    resource_class: small
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build with Depot
          command: depot build .
 
workflows:
  run_build:
    jobs:
      - build

Note: The setup_remote_docker step is required for the docker executor if you want to execute Docker commands in your build before or after the depot CLI builds your image. See the examples below

Examples

The examples below use the machine executor. However, the same commands can be used with the docker executor as well.

Build multi-platform images without emulation in CircleCI

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

version: 2.1
 
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build multi-architecture image
          command: |
            depot build --platform linux/amd64,linux/arm64 .
workflows:
  run_build:
    jobs:
      - build

Build and push to Docker Hub

This examples assumes you have set the DOCKERHUB_PASS and DOCKERHUB_USERNAME environment variables in your CircleCI project settings.

version: 2.1
 
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build and push to Docker Hub with Depot
          command: |
            echo "$DOCKERHUB_PASS" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            depot build -t <your-docker-hub-repository> --push .
workflows:
  run_build:
    jobs:
      - build

Build and push to Amazon ECR

This examples assumes you have set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_ECR_REGISTRY_ID environment variables in your CircleCI project settings. See the circleci/aws-ecr orb documentation for more information.

version: 2.1
orbs:
  aws-ecr: circleci/aws-ecr@8.2.1
 
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - aws-ecr/ecr-login:
          region: us-east-1
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build and push to Amazon ECR with Depot
          command: |
            depot build -t <your-amazon-ecr-repo> --push .
workflows:
  run_build:
    jobs:
      - build

Build and load the image back into the CircleCI job for testing

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

version: 2.1
 
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build and push to Docker Hub with Depot
          command: |
            depot build --load .
workflows:
  run_build:
    jobs:
      - build

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.

version: 2.1
 
jobs:
  build:
    machine: true
    resource_class: medium
    steps:
      - checkout
      - run:
          name: Install Depot
          command: |
            curl -L https://depot.dev/install-cli.sh | sudo env DEPOT_INSTALL_DIR=/usr/local/bin sh
      - run:
          name: Build and push to Docker Hub with Depot
          command: |
            echo "$DOCKERHUB_PASS" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
            depot build -t <your-docker-hub-repository> --push --load .
workflows:
  run_build:
    jobs:
      - build