Skip to content
Source
Sign inSign up

Deploy with OIDC

CI / Secrets and trust

Deploy to a cloud with OIDC

Your deploy job needs keys for AWS, Google Cloud or Azure, and a cloud key that you save as a CI secret works for months. With OIDC, you save no cloud key: the job asks the forge for a signed token, and trades the token with the cloud for short-lived keys.

5 min read

If a saved key leaks, anyone who has it can use your cloud until you revoke it. The OIDC token is good for 5 minutes, and only for the one audience that the job names.

Pick your cloud:

How a job asks for the token

  • Add permissions: { idToken: true } to the job.
  • In a function step, ctx.idToken({ audience }) returns the token.
  • A command step can get the token with curl and TANSTACK_SOURCE_OIDC_REQUEST_URL: curl -fsS "$TANSTACK_SOURCE_OIDC_REQUEST_URL?audience=sts.amazonaws.com" | jq -r .token.
  • The cloud trusts the issuer https://source.tanstack.com/oidc.

Note

The issuer is the address of the site, then /oidc. On another deployment of TanStack Source, use its address.

Which runs get a token

RunGets a token
protectedyes
trustedyes
untrusted, like a pull request from a forkno
A hidden workflowno
A private pull requestno
  • A pull request run takes idToken from the job of the same name on the base branch, as it does all permissions. So push the job to the default branch first.
  • When the run gets no token, the run shows a warning, like idToken: true needs a trusted run; this run is untrusted.
  • A local run (src ci run) has no token.

Trust levels and secrets says which events give which level.

Keep the token out of the logs

The forge does not mask the token in logs.

  • Do not print the token. Step logs can be public, and a printed token works for 5 minutes.
  • Send the token in a request header or body, never in a URL. The egress audit records the URL of each request.
  • Ask for the token right before you use it.

When ctx.idToken() fails

The step fails with the reason. A refusal of the forge reads GET /oidc/token was refused: HTTP <status>: <reason>.

ErrorCause and fix
HTTP 403: This job did not ask for idToken: true, or its run may not have itThe job has no permissions: { idToken: true }, or its run gets no token (see Which runs get a token). For a pull request, the base branch must have the permission. Read the warnings of the run.
HTTP 403: a hidden workflow's job gets no OIDC tokenHidden workflows get no token. Move the job to a workflow file in .source/workflows/.
HTTP 400: an OIDC token needs an audience of 1 to 256 charactersGive an audience of at most 256 characters. An empty audience fails before the request: ctx.idToken needs an audience.
HTTP 400: the audience source-app:<slug> is for app tokens onlyAn audience that starts with source-app: belongs to the job tokens of apps. To send a token to an app, name the app on the job: see Use an app from a CI job.
HTTP 503: OIDC is not set up on this deploymentThe site has no signing key. Ask the operator of the site to set one.
ctx.idToken works only in a forge CI run, not in a local runsrc ci run gets no token. Run the steps that need it on the forge.

npm and PyPI

npm and PyPI trusted publishing accept only the CI providers on their own lists, and TanStack Source is not on them yet. Publish with a token secret, like NPM_TOKEN. See Add a CI secret.

The claims of a token

The forge signs each token with RS256, with the kid of its key in the header. A cloud reads the public keys from https://source.tanstack.com/oidc/jwks, through the discovery document at https://source.tanstack.com/oidc/.well-known/openid-configuration.

ClaimValue
isshttps://source.tanstack.com/oidc
audThe audience that the job asked for.
iat, nbfWhen the forge made the token, in seconds since 1970 (Unix time).
expiat plus 300. The token is good for 5 minutes.
jtiA random id, new for each token.
subrepo:<owner>/<repo>:ref:<ref>, or repo:<owner>/<repo>:pull_request for a pull request run.
repository<owner>/<repo>.
repository_idThe id of the repository on the forge.
repository_ownerThe user or organization that owns the repository.
repository_owner_idThe id of that owner on the forge.
refThe full ref of the run, like refs/heads/main or refs/tags/v1.0.0. For a pull request run, refs/pull/<number>/head.
head_refPull request runs only: the name of the head branch, like feature.
shaThe commit that the run tests.
eventpush, pull_request, schedule, manual or after.
workflowThe name of the workflow, from defineWorkflow.
jobThe name of the job.
run_idThe id of the run.
actorThe user name of the person that the job acts for, or system.
actor_idThe id of that person on the forge, or system.
trusttrusted or protected.
workflow_ref<owner>/<repo>/<workflow file>@<ref>, like acme/app/.source/workflows/deploy.ts@refs/heads/main.
job_workflow_refThe same as workflow_ref.
runner_environmentAlways source-hosted.

A pull request run never puts its head branch in ref or sub, because a fork can name its branch main. So a trust policy that matches ref:refs/heads/main never matches a pull request. head_ref is for information only. Do not match on it.