Use Remote Caching from External CI/CD

You can use Vercel Remote Cache with Turborepo from an external CI/CD provider, so your pipelines share the same cache as your team. There are two ways to authenticate:

• OpenID Connect (OIDC): configure a policy that allows exchanging the CI/CD provider's OIDC tokens for short-lived Turborepo access tokens that grant access to Remote Cache (recommended).
• Personal Access Token (PAT): configure a long-lived, team-scoped PAT as a secret in your CI/CD provider (use when OIDC is not an option).

To set up Remote Caching on your own machine instead, see Remote Caching.

When you use OIDC to authenticate, you exchange your CI/CD provider's OIDC token for a short-lived Turborepo access token and set it in the TURBO_TOKEN environment variable.

Unlike a Personal Access Token (PAT), the Turborepo access token

• is short-lived
• only grants access to Vercel Remote Cache
• is associated to your team, rather than a specific team member

Follow the steps below to set it up.

1. Create an OIDC policy

   On the Vercel dashboard, go to your team's Settings → Build and Deployment → OIDC Policies for CLI Access, then click Add next to Turborepo CLI Policies.

2. Configure the OIDC policy

   Clicking Add opens a form to add a Turborepo CLI policy. Fill out the form with a policy name. If your CI/CD provider is listed, select it; otherwise, you can configure specific OIDC issuer and claims to match on.

   For example, if you are using GitHub, select your GitHub account and repository that hosts the CI/CD workflows you want to grant access to. You can optionally restrict the policy to a specific workflow or branch, and customize the audience.

3. Add the TURBO_TEAM repository variable

   Create a repository variable named TURBO_TEAM set to your team slug, which is the part after vercel.com/ in your team URL. For example, the slug for vercel.com/acme is acme.

   The exact steps depend on your CI/CD provider. For GitHub, use the GitHub CLI from your repository:

   Terminal

   gh variable set TURBO_TEAM --body "your-team-slug"

   Or add it through the GitHub UI under Settings → Secrets and variables → Actions, on the Variables tab.

   Using a repository variable rather than a secret ensures CI/CD providers like GitHub don't censor your team name in log output.

4. Exchange the OIDC token in your job and set the environment variable

   GitHubOther

   Add vercel/setup-turborepo-remote-cache-action before any step that runs turbo. The action needs the id-token: write permission so it can request a GitHub OIDC token, exchange it for a short-lived Turborepo access token, and set TURBO_TOKEN and TURBO_TEAM for later steps.

   .github/workflows/ci.yml

   # ...
    
   jobs:
     build:
       name: Build and Test
       timeout-minutes: 15
       runs-on: ubuntu-latest
       permissions:
         contents: read
         id-token: write
    
       steps:
         - name: Check out code
           uses: actions/checkout@v4
           with:
             fetch-depth: 2
    
         - name: Set up Turborepo Remote Cache
           uses: vercel/setup-turborepo-remote-cache-action@v1.0.0
           with:
             team: ${{ vars.TURBO_TEAM }}
       # ...

   If you create multiple OIDC policies on your team, Vercel will try to match your GitHub OIDC token against each of them. If more than one policy matches, then you will need to pass the ID of the OIDC policy you intend to use in the policy input; otherwise, you will receive an error.

   For any other provider, request an OIDC token from it with the audience your policy expects, then exchange that token for a short-lived Turborepo access token. Set the result as TURBO_TOKEN and your team slug as TURBO_TEAM before running turbo:

   exchange-oidc-token.sh

   # $OIDC_TOKEN: the OIDC token issued by your CI/CD provider
   # $TURBO_TEAM: your Vercel team ID or slug
    
   export TURBO_TOKEN=$(curl -sS -f -X POST https://api.vercel.com/login/oauth/token \
     --data "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
     --data "client_id=cl_kyUx2zVvA4MGptBohkmtYHJly2XltXzD" \
     --data "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
     --data "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
     --data-urlencode "team_id_or_slug=$TURBO_TEAM" \
     --data-urlencode "subject_token=$OIDC_TOKEN" \
     | jq -r '.access_token')

   If you create multiple OIDC policies on your team, Vercel will try to match your CI/CD provider's OIDC token against each of them. If more than one policy matches, then you will need to pass the ID of the OIDC policy you intend to use in the policy_id parameter; otherwise you will receive an error.

   You can add the policy_id parameter like this: --data-urlencode "policy_id=$POLICY_ID".

If your CI/CD provider doesn't support OIDC, you can authenticate with a Personal Access Token (PAT).

Scope the PAT to the Vercel team you want to share artifacts with, so that you don't grant it more access than necessary.

Then add the following environment variables to your workflow to make them available to your turbo commands:

• TURBO_TOKEN: PAT scoped to the Vercel team to share artifacts with
• TURBO_TEAM: slug of the Vercel team to share artifacts with

1. Create a scoped access token

   Create a scoped access token in the Vercel dashboard, then copy the value somewhere safe. You'll need it in the next step.

2. Add the TURBO_TOKEN secret

   Create a secret named TURBO_TOKEN set to the access token you just created. The exact steps depend on your CI/CD provider. For GitHub, use the GitHub CLI:

   Terminal

   gh secret set TURBO_TOKEN

   Paste the token value when prompted. Or add it through the GitHub UI under Settings → Secrets and variables → Actions, on the Secrets tab.

3. Add the TURBO_TEAM variable

   Create a repository variable named TURBO_TEAM set to your team slug, which is the part after vercel.com/ in your team URL. For example, the slug for vercel.com/acme is acme.

   The exact steps depend on your CI/CD provider. For GitHub, use the GitHub CLI from your repository:

   Terminal

   gh variable set TURBO_TEAM --body "your-team-slug"

   Or add it through the GitHub UI under Settings → Secrets and variables → Actions, on the Variables tab.

   Using a repository variable rather than a secret ensures CI/CD providers like GitHub don't censor your team name in log output.

4. Set the environment variables on your job

   The exact steps will vary depending on your CI/CD provider. For example, if you are using GitHub, provide the environment variables to any job that runs turbo.

   .github/workflows/ci.yml

   # ...
    
   jobs:
     build:
       name: Build and Test
       timeout-minutes: 15
       runs-on: ubuntu-latest
       env:
         TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
         TURBO_TEAM: ${{ vars.TURBO_TEAM }}
    
       steps:
         - name: Check out code
           uses: actions/checkout@v4
           with:
             fetch-depth: 2
       # ...

• Remote Caching
• setup-turborepo-remote-cache-action