GitHub Actions - TrueFoundry Docs

Every GitHub Actions job can request a signed OIDC JWT from https://token.actions.githubusercontent.com. With Workload Identity Federation, the job exchanges that JWT for a short-lived TrueFoundry access token — no long-lived Virtual Account token stored as a repository secret. TrueFoundry requires a repository claim match on the Virtual Account Claims (or Agent Subject) mapping. For concepts and the shared exchange API, see Workload Identity Federation.

Prerequisites

A GitHub repository where you can edit workflows and grant id-token: write.
A Virtual Account or Agent with the permissions the job needs.

Configure the workflow

GitHub only issues an identity token when the job requests it:

permissions:
  id-token: write
  contents: read

Fetch a token with the audience you will register on TrueFoundry (for example truefoundry):

- name: Fetch GitHub OIDC token
  run: |
    curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=truefoundry" \
      | jq -r .value > "$RUNNER_TEMP/gha-jwt"

Or with actions/github-script:

- name: Fetch GitHub OIDC token
  uses: actions/github-script@v7
  with:
    script: |
      const fs = require('fs');
      const token = await core.getIDToken('truefoundry');
      fs.writeFileSync(`${process.env.RUNNER_TEMP}/gha-jwt`, token);

Typical claims on the JWT:

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "truefoundry",
  "sub": "repo:your-org/your-repo:ref:refs/heads/main",
  "repository": "your-org/your-repo",
  "repository_owner": "your-org",
  "ref": "refs/heads/main"
}

Configure TrueFoundry

Settings > Security & Access > Identity Providers → add provider type GitHub.
Set:

Field	Value
Issuer URL	`https://token.actions.githubusercontent.com`
Allowed Audiences	Same audience you requested (for example `truefoundry`)
JWKS URI	`https://token.actions.githubusercontent.com/.well-known/jwks`

Map the Virtual Account (or Agent):

Virtual Account — Claims

identity_provider_mapping:
  - identity_provider: github-actions
    claims:
      repository: your-org/your-repo

Agent — Subject (YAML key is still claims)

identity:
  type: identity-provider-backed
  identity_provider_mapping:
    - identity_provider: github-actions
      claims:
        repository: your-org/your-repo

Required key for github: repository. You may add further claim matches (for example ref) when your token includes them and you want to pin them.

Exchange and call TrueFoundry

- name: Exchange for TrueFoundry token
  env:
    # Issuer origin; exchange path is /{tenant}/oauth2/v1/token (no /api/svc)
    TFY_CONTROL_PLANE: https://<tenant-host-origin>
    TFY_TENANT: <tenant>
  run: |
    WORKLOAD_JWT=$(cat "$RUNNER_TEMP/gha-jwt")
    curl -sS "$TFY_CONTROL_PLANE/$TFY_TENANT/oauth2/v1/token" \
      -H 'Content-Type: application/json' \
      -d "{
        \"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\",
        \"subject_token\": \"$WORKLOAD_JWT\",
        \"subject_token_type\": \"urn:ietf:params:oauth:token-type:jwt\",
        \"tfy_subject\": \"virtual_account:<virtual-account-name>\"
      }" > "$RUNNER_TEMP/tfy-token.json"
    echo "TFY_ACCESS_TOKEN=$(jq -r .access_token "$RUNNER_TEMP/tfy-token.json")" >> "$GITHUB_ENV"

Use TFY_ACCESS_TOKEN as Authorization: Bearer against the AI Gateway or APIs. For Agents, set tfy_subject to agent:<agent-name>. Full exchange details: Workload Identity Federation.

Scope the mapping

Prefer repository: your-org/your-repo over a broad org-wide pattern.
Add optional claim matches (for example a protected branch ref) when only specific workflows should authenticate.
Do not store a long-lived VAT in GitHub Secrets when federation is available.

​Prerequisites

​Configure the workflow

​Configure TrueFoundry

​Exchange and call TrueFoundry

​Scope the mapping

Prerequisites

Configure the workflow

Configure TrueFoundry

Exchange and call TrueFoundry

Scope the mapping