GitHub Actions

Authentication

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

OIDC token

The easiest option is to use GitHub's OIDC token as authentication for depot build. Our depot/build-push-action & depot/bake-action supports authentication via OIDC.

Project token

You can inject a project access token into the Action workflow 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 Action workflow 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

Option 1 — Depot build and push action

We publish a GitHub Action (depot/build-push-action) that implements the same inputs and outputs as docker/build-push-action but uses the depot CLI to run the Docker build.

jobs:
  build:
    runs-on: ubuntu-20.04
    # Set permissions if you're using OIDC token authentication
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      - 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>
          # Pass project token or user access token if you're not using OIDC token authentication
          token: ${{ secrets.DEPOT_TOKEN }}
          context: .

Option 2 — Depot bake action

Another option is to make use of the GitHub Action (depot/bake-action) that allows you to build all of the images defined in an HCL, JSON or Docker Compose file. Bake is a great action to use when you are looking to build multiple images with a single build request.

jobs:
  build:
    runs-on: ubuntu-20.04
    # Set permissions if you're using OIDC token authentication
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      - name: Bake Docker images
        uses: depot/bake-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>
          files: docker-bake.hcl

Option 3 — Depot CLI

You can also use the GitHub Action (depot/setup-action) that installs the depot CLI to run Docker builds directly from your existing workflows.

jobs:
  build:
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      - run: depot build --project <your-project-id> --push --tag repo/image:tag .
        env:
          DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}

Examples

Build multi-platform images natively without emulation

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

name: Build image
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - 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 }}
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: user/app:latest

Build and push to Docker Hub with OIDC token exchange

This example uses our recommended way of authenticating builds from GitHub Actions to Depot via OIDC trust relationships. It builds an image with a tag to be pushed to DockerHub.

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@v4
 
      - 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>
          context: .
          push: true
          tags: user/app:latest

Build and push to Docker Hub with Depot API tokens

This example uses the token input for our depot/build-push-action to authenticate builds from GitHub Actions to Depot. Of course, the token input can be a user token. Still, we recommended using a project token to limit the token's scope to a single project.

name: Build image
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - 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 }}
          context: .
          push: true
          tags: user/app:latest

Build and push an image to Amazon ECR

Use the configure-aws-credentials and amazon-ecr-login actions from AWS to configure GitHub Actions to authenticate to your ECR registry. Then build and push the image to your ECR registry using the depot/build-push-action.

name: Build image
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      # Login to ECR
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1.6.1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: <aws-region>
 
      - name: Login to Amazon ECR
        id: ecr-login
        uses: aws-actions/amazon-ecr-login@v1.5.0
 
      - 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 }}
          context: .
          push: true
          tags: ${{ steps.ecr-login.outputs.registry }}/<your-app>:latest

Build and push an image to GCP Artifact Registry

Use the setup-gcloud action from GCP to configure gcloud in GitHub Actions to authenticate to your Artifact Registry. Then build and push the image to your GCP registry using the depot/build-push-action.

name: Build image
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      # Login to Google Cloud registry
      - uses: google-github-actions/setup-gcloud@v0.6.0
        with:
          project_id: gcp-project-id
          service_account_key: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}
 
      - name: Configure docker for GCP
        run: gcloud auth configure-docker
 
      - 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 }}
          context: .
          push: true
          tags: <gcp-region>-docker.pkg.dev/<gcp-project-id>/<your-app>:latest

Build and push an image to Azure Container Registry with OIDC

After adding a trust relationship between Depot and GitHub Actions, you'll be able to log in to Azure Container Registry using the docker/login-action and build and push an image to the registry using the depot/build-push-action via the image tag(s).

name: Build and push to Azure Container Registry
 
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 Azure Container Registry
        uses: docker/login-action@v2
        with:
          registry: <registry-name>.azurecr.io
          username: ${{ secrets.AZURE_CLIENT_ID }}
          password: ${{ secrets.AZURE_CLIENT_SECRET }}
 
      - 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>
          context: .
          push: true
          tags: <registry-name>.azurecr.io/<image-name>:<tag>

Build and push to multiple registries

Build and tag an image to push to multiple registries by logging into each one individually.

name: Build image
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1.6.1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: <aws-region>
 
      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
 
      - name: Login to Amazon ECR
        id: ecr-login
        uses: aws-actions/amazon-ecr-login@v1.5.0
 
      - 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 }}
          context: .
          push: true
          tags: |
            <docker-hub-organization>/<your-app>:latest
            ${{ steps.ecr-login.outputs.registry }}/<your-app>:latest

Export an image to Docker

By default, like docker buildx, Depot doesn't return the built image to the client. However, for cases where you need the built image in your GitHub Actions workflow, you can pass the load: true input, and Depot will return the image to the workflow.

name: Build image
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - 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 load
        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 }}
          context: .
          load: true
          tags: test-container
 
      - name: Run integration test with built container
        run: ...

Build an image with Software Bill of Materials

Build an image with a Software Bill of Materials (SBOM) using the sbom and sbom-dir inputs. The sbom input will generate an SBOM for the image, and the sbom-dir input will output the SBOM to the specified directory. You can then use the actions/upload-artifact action to upload the SBOM directory as a build artifact.

name: Build an image with SBOM
 
on:
  push:
    branches:
      - main
 
jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
 
      - name: Set up Depot CLI
        uses: depot/setup-action@v1
 
      - name: Build and load
        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 }}
          context: .
          sbom: true
          sbom-dir: ./sbom-output
 
      - name: upload SBOM directory as a build artifact
        uses: actions/upload-artifact@v3.1.0
        with:
          path: ./sbom-output
          name: 'SBOM'