OIDC with Depot CI

Depot CI supports OpenID Connect (OIDC) so your workflows can authenticate with cloud providers like AWS, GCP, and Azure using short-lived tokens instead of static credentials.

How it works

OIDC (OpenID Connect) is a standard for token-based authentication. Instead of storing long-lived credentials like API keys or passwords in your CI, your job receives a short-lived signed token that proves its identity. Your cloud provider verifies the token against Depot CI's public endpoint and grants access based on the claims inside it.

Depot CI automatically issues a signed JSON Web Token (JWT) to each job.

To use OIDC with Depot CI you'll need to configure a trust relationship between Depot CI and your cloud provider, then request the token in your workflows and use it to authenticate.

The Depot CI OIDC token

Each job in Depot CI receives a JWT. You must set permissions: id-token: write in your workflow YAML for the token to be issued.

The following is an example token:

{
  "actor": "my-username",
  "actor_id": "1000000",
  "aud": ["sts.amazonaws.com"],
  "base_ref": "",
  "event_name": "push",
  "exp": 1773766359,
  "head_ref": "",
  "iat": 1773766059,
  "iss": "https://identity.depot.dev",
  "job_id": "job_xxxxxxxxxxxx",
  "org_id": "org_xxxxxxxxxxxxxxxxxxxx",
  "ref": "refs/heads/main",
  "ref_type": "branch",
  "repository": "my-org/my-repo",
  "repository_id": "123456789",
  "repository_owner": "my-org",
  "repository_owner_id": "12345678",
  "repository_visibility": "private",
  "run_attempt": "1",
  "run_id": "run_xxxxxxxxxxxx",
  "run_number": "42",
  "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "sub": "spiffe://identity.depot.dev/org/org_xxxxxxxxxxxxxxxxxxxx/ci/github/my-org/my-repo/ref/refs/heads/main/sandbox/snd_xxxxxxxxxxxx",
  "workflow": "ci.yaml",
  "workflow_ref": "my-org/my-repo/ci.yaml@refs/heads/main",
  "workflow_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}

Restrict trust policies with the subject claim

The sub claim is how you restrict a trust policy to a specific org, repository, or branch. It reads left to right, from the most stable identifier to the most ephemeral. The full claim has the following format:

spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/<ref>/sandbox/<sandboxID>

Match the segments you want to restrict, and use a wildcard for the rest. Do not include the final segment in the match, because Depot generates a new sandbox ID for each job, and a policy that pins it stops matching on the next run.

Common patterns:

• Everything in your GitHub organization: spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/*
• A specific repository: spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/*
• A specific branch: spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/refs/heads/main/sandbox/*

Matching precisely on your cloud provider

How you pin the identity beyond the sub prefix depends on which claims your cloud provider exposes as trust-policy condition keys.

On AWS, a self-managed OIDC provider surfaces only the standard claims as IAM condition keys: aud and sub (along with amr, email, and oaud). The GitHub-compatible and Depot-specific claims (repository, repository_owner, ref, and the rest) travel inside the token but are not available as identity.depot.dev:<claim> condition keys, so a trust policy that references them never matches. On AWS, match the sub claim with StringLike as shown in Example: Configure OIDC with AWS. The sub value already encodes the org, owner, repo, and ref, so a single sub condition is enough to restrict access to a repository or branch.

On providers that map arbitrary token claims into their trust conditions, such as GCP workload identity federation, you can match the flat claims directly (repository, repository_owner, ref, and the rest of the claim reference below). These are exact-match values that carry the same meaning as their GitHub Actions equivalents, so on those platforms you can pin them exactly instead of wildcarding the sub path.

Configure OIDC with your cloud provider

The general steps are the same for any OIDC-compatible provider:

1. Add https://identity.depot.dev as a trusted OIDC issuer.
2. Create a role or service account that grants access based on token claims.
3. Request the token in your workflow and use it to authenticate.

Example: Configure OIDC with AWS

1. Add Depot CI as an identity provider in AWS IAM.

   • Provider URL: https://identity.depot.dev
   • Audience: sts.amazonaws.com

2. Create an IAM role with a trust policy.

   Scope the trust policy using the sub claim (matching on Depot org and GitHub repository) and aud:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {"Federated": "arn:aws:iam::ACCOUNT:oidc-provider/identity.depot.dev"},
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "identity.depot.dev:aud": "sts.amazonaws.com"
           },
           "StringLike": {
             "identity.depot.dev:sub": "spiffe://identity.depot.dev/org/<orgID>/ci/github/my-org/my-repo/*"
           }
         }
       }
     ]
   }

   Copy code

   The sub claim scopes trust to a specific Depot org and GitHub repository.

3. Use the role in a workflow.

   Set permissions: id-token: write at the job level. Depot CI automatically injects the token request credentials into the environment, so aws-actions/configure-aws-credentials works without any extra configuration.

   jobs:
     deploy:
       runs-on: depot-ubuntu-latest
       permissions:
         id-token: write
         contents: read
       steps:
         - uses: actions/checkout@v4
         - uses: aws-actions/configure-aws-credentials@v4
           with:
             role-to-assume: arn:aws:iam::123456789012:role/my-role
             aws-region: us-east-1
         - run: aws s3 ls

   Copy code

Migrate from GitHub Actions OIDC

permissions: id-token: write is required in your workflow YAML, the same as GitHub Actions.

The following needs to change on the cloud provider side when moving from GitHub Actions to Depot CI:

To use Depot CI with OIDC, follow these steps:

1. Add https://identity.depot.dev as a new identity provider in your cloud provider.

2. Create a new trust policy for Depot CI. Creating a new policy rather than modifying your existing GitHub Actions trust policy lets both providers work in parallel during the transition.

3. If your existing trust policy conditions on sub, update it to use the Depot CI format:

   spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/<ref>/sandbox/<sandboxID>

   Copy code

   For more specific matches, use a wildcard:

   • Everything in your GitHub organization:

     spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/*

     Copy code

   • A specific repository:

     spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/*

     Copy code

   • A specific branch:

     spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/<ref>/sandbox/*

     Copy code

Token claim reference

Standard claims

GitHub Actions-compatible claims

Depot-specific claims