Authentication

We provide three different options you can use to authenticate your build to our remote Docker builders via the depot CLI.

User access tokens

You can generate an access token tied to your Depot account that can be used for builds in any project in any organization you have access. When you run depot login we authenticate your account and generate a new user access token that all builds from your machine use by default. It is recommended to only use these for local development and not in CI environments.

To generate a user access token, you can go through the following steps:

1. Open your Account Settings
2. Enter a description for your token under API Tokens
3. Click Create token

Project tokens

Unlike user access tokens, project tokens are tied to a specific project in your organization and not a user account. These are ideal for building images with Depot from your existing CI provider. They are not tied to a single user account and are restricted to a single project in a single organization.

To generate a project token, you can go through the following steps:

1. Open your Project Details page by clicking on a project from your projects list
2. Click the Settings button next to your project ID
3. Enter a token description and click create token

OIDC trust relationships

If you use GitHub Actions, CircleCI, or Buildkite as your CI provider, we can directly integrate with GitHub Actions OIDC, CircleCI OIDC, Buildkite OIDC, or Mint via trust relationships. This token exchange is a great way to plug Depot into your existing Actions workflows, CircleCI jobs, or Buildkite pipelines, as it requires no static secrets, and credentials are short-lived.

You configure a trust relationship in Depot that allows your GitHub Actions workflows, CircleCI jobs, or Buildkite pipelines to access your project via a token exchange. The CI job requests an access token from Depot, and we check the request details to see if they match a configured trust relationship for your project. If everything matches, we generate a temporary access token and return it to the job. This temporary access token is only valid for the duration of the job that requested it.

Adding a trust relationship for GitHub Actions

To add a trust relationship for GitHub Actions, you can go through the following steps:

1. Open your Project Details page by clicking on a project from your projects list
2. Click the Settings button next to your project ID
3. Click the Add trust relationship button
4. Select GitHub as the provider
5. Enter a GitHub User or Organization for the trust relationship
6. Enter the name of the GitHub repository that will build images via Depot (Note: this is the repository name, not the full URL and it must match the repository name exactly)
7. Click Add trust relationship

Adding a trust relationship for CircleCI

To add a trust relationship for CircleCI, you can go through the following steps:

1. Open your Project Details page by clicking on a project from your projects list
2. Click the Settings button next to your project ID
3. Click the Add trust relationship button
4. Select CircleCI as the provider
5. Enter your CircleCI organization UUID (this is found in your CircleCI organization settings)
6. Enter your CircleCI project UUID (this is found in your CircleCI project settings)
7. Click Add trust relationship

Note: CircleCI requires entering your organization and project UUID, not the friendly name of your organization or project.

Adding a trust relationship for Buildkite

To add a trust relationship for Buildkite, you can go through the following steps:

1. Open your Project Details page by clicking on a project from your projects list
2. Click the Settings button next to your project ID
3. Click the Add trust relationship button
4. Select Buildkite as the provider
5. Enter the organization slug (i.e., buildkite.com/<org-slug>)
6. Enter the pipeline organization slug (i.e., buildkite.com/<org-slug>/<pipeline-slug>)
7. Click Add trust relationship

Adding a trust relationship for Mint

To add a trust relationship for Mint, you can go through the following steps:

1. Open your Project Details page by clicking on a project from your projects list
2. Click the Settings button next to your project ID
3. Click the Add trust relationship button
4. Select Mint as the provider
5. Enter your Mint Vault subject you configured here
6. Click Add trust relationship