This GitHub Action is for building and pushing Docker images with Depot. The action implements the same inputs and outputs as the docker/build-push-action, but uses the depot CLI to execute the build.

Depot allows you to build Docker images 5-20x faster on GitHub Actions through optimized build compute and a Docker cache that’s persisted between builds on SSDs.

Depot also supports native multi-architecture builds.

• Build and push a Docker image with Depot - GitHub Action
  • Table of Contents
  • Setup
  • Usage
    • Authentication
    • Differences from docker/build-push-action
  • Inputs
    • Depot-specific inputs
    • General inputs
  • Outputs
  • Examples
    • Basic build and push with OIDC token exchange
    • Basic build and push with Depot API tokens
    • Build multi-platform images
    • Other examples
  • License

The depot CLI will need to be available in your workflow, you can use the depot/setup-action to install it:

steps:
  - uses: depot/setup-action@v1

This action implements the same inputs and outputs as the docker/build-push-action. You will need to supply your project ID and Depot authentication information, although both can be inferred from the environment. See below for more details.

This action needs a Depot API token to communicate with your project's builders. You can supply this one of three ways. The third, using OICD, is the preferred method, but you can also supply a token directly.

1. You can supply a user or project API token via the token input:

   steps:
     - uses: depot/build-push-action@v1
       with:
         token: ${{ secrets.DEPOT_TOKEN }}

2. You can supply a user or project API token via the DEPOT_TOKEN environment variable:

   steps:
     - uses: depot/build-push-action@v1
       env:
         DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}

3. Depot supports GitHub's OpenID Connect tokens via a trust relationship, so your Actions builds can securely authenticate with your Depot projects without any static access tokens. To configure the trust relationship, visit your Depot project settings, then add your repository and desired workflow config to Trust Relationships. Then in your workflow, enable the id-token: write permission:

   permissions:
     # allow issuing OIDC tokens for this workflow run
     id-token: write
     # allow at least reading the repo contents, add other permissions if necessary
     contents: read
   steps:
     # no need to provide a DEPOT_TOKEN
     - uses: depot/build-push-action@v1

1. Authentication — this action needs to authenticate with a Depot API token to communicate with your project's builders (see above).

2. If you have not configured a depot.json file with depot init, you can explicitly specify your project ID via the project input:

   steps:
     - uses: depot/build-push-action@v1
       with:
         project: abc123xyz

3. The builder input is not supported - this action always runs builds using Depot's hosted builders, if you need to route builds to a local buildx builder, you should use the docker/build-push-action.

4. Depending on how you are using cache-from / cache-to, you may be able to remove those options. Depot's builders launch with persistent local SSD cache, so unless you wish to push your cache to a registry for other reasons, you can remove them:

   steps:
     -
   -  uses: docker/build-push-action@v1
   +  uses: depot/build-push-action@v1
      with:
   -    cache-from: type=gha
   -    cache-to: type=gha,mode=max

The following inputs can be used as step.with keys and match the inputs from docker/build-push-action:

Below are examples of how to use depot/build-push-action to build your Docker images using Depot builders. For all examples, it is assumed that you are either specifying the Depot project ID via the project or input, environment variable, or using a depot.json file.

See our trust relationship documentation for details on configuring this exchange.

name: Build image

on:
  push:
    branches:
      - main

jobs:
  docker-image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Set up Depot CLI
        uses: depot/setup-action@v1

      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: depot/build-push-action@v1
        with:
          # if no depot.json file is at the root of your repo, you must specify the project id
          project: <your-depot-project-id>
          push: true
          tags: user/app:latest

You can use either Depot project tokens or user tokens in the token input.

Note: Project tokens are the recommendation if OIDC tokens are not an option.

name: Build image

on:
  push:
    branches:
      - main

jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Set up Depot CLI
        uses: depot/setup-action@v1

      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: depot/build-push-action@v1
        with:
          # if no depot.json file is at the root of your repo, you must specify the project id
          project: <your-depot-project-id>
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          push: true
          tags: user/app:latest
          build-args: |
            FOO=bar

Depot supports building truly native multi-platform images, no emulation needed.

name: Build image

on:
  push:
    branches:
      - main

jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      - name: Set up Depot CLI
        uses: depot/setup-action@v1

      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: depot/build-push-action@v1
        with:
          # if no depot.json file is at the root of your repo, you must specify the project id
          project: <your-depot-project-id>
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          platforms: linux/amd64,linux/arm64
          push: true
          tags: user/app:latest

• Build and push image to Amazon ECR
• Build and push image to GCP Artifact Registry
• Build and push to multiple registries
• Export image to Docker
• Lint and Build image
• Build image with Software Bill of Materials (SBOM)

MIT License, see LICENSE.

Code derived from docker/build-push-action copyright 2013-2018 Docker, Inc., Apache License, Version 2.0.