If you're looking to use our fully-managed GitHub Actions Runners as a drop-in replacement for your existing runners, head over to Quickstart for GitHub Actions Runners.
If you're looking to use Depot just for your container image builds in GitHub Actions, read on.
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.
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.
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.
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.
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: .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.hclYou 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 }}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:latestThis 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:latestThis 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:latestUse 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>:latestUse 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>:latestAfter 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 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>:latestBy 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 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'