We use cookies to understand how people use Depot.
Integrations

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 supports authentication via OIDC.

Project token

A project access token can be injected into the Action workflow for depot CLI authentication. This is a token that is tied to a specific project in your organization and not a user.

User access token

It is also possible to generate a user access token that can be injected into the Action workflow for depot CLI authentication. This is a token that is 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 to.

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:
      - uses: actions/checkout@v3
      # The depot CLI still needs to be available in your workflow
      - uses: depot/setup-action@v1
      - uses: depot/build-push-action@v1
        with:
          context: .
          push: true
          tags: |
            ...
          # Pass project token or user access token if you're not using OIDC token authentication
          token: ${{ secrets.DEPOT_TOKEN }}

Option 2 — Depot CLI

Another option is to make use of the GitHub Action (depot/setup-action) that installs the depot CLI to run Docker builds directly from your existing workflows.

Note: This GitHub Action does not support the OIDC token authentication method.

jobs:
  build:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v3
      - uses: depot/setup-action@v1
      - run: depot build --push --tag repo/image:tag .
        env:
          DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}

Examples

Basic build and push to DockerHub 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 that is 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: 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:
          push: true
          tags: user/app:latest

Basic build and push with Depot API tokens

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

name: Build image

on:
  push:
    branches:
      - main

jobs:
  docker-image:
    runs-on: ubuntu-latest
    steps:
      - 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:
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          push: true
          tags: user/app:latest

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: 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:
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          platforms: linux/amd64,linux/arm64
          push: true
          tags: user/app:latest

Build and push 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: 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:
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          push: true
          tags: ${{ steps.ecr-login.outputs.registry }}/<your-app>:latest

Build and push 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: 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:
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          push: true
          tags: <gcp-region>-docker.pkg.dev/<gcp-project-id>/<your-app>:latest

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: 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:
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          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. 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: 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:
          token: ${{ secrets.DEPOT_PROJECT_TOKEN }}
          load: true
          tags: test-container

      - name: Run integration test with built container
        run: ...