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
curlandTANSTACK_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
| Run | Gets a token |
|---|---|
protected | yes |
trusted | yes |
untrusted, like a pull request from a fork | no |
| A hidden workflow | no |
| A private pull request | no |
- A pull request run takes
idTokenfrom 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>.
| Error | Cause and fix |
|---|---|
HTTP 403: This job did not ask for idToken: true, or its run may not have it | The 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 token | Hidden 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 characters | Give 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 only | An 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 deployment | The 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 run | src 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.
| Claim | Value |
|---|---|
iss | https://source.tanstack.com/oidc |
aud | The audience that the job asked for. |
iat, nbf | When the forge made the token, in seconds since 1970 (Unix time). |
exp | iat plus 300. The token is good for 5 minutes. |
jti | A random id, new for each token. |
sub | repo:<owner>/<repo>:ref:<ref>, or repo:<owner>/<repo>:pull_request for a pull request run. |
repository | <owner>/<repo>. |
repository_id | The id of the repository on the forge. |
repository_owner | The user or organization that owns the repository. |
repository_owner_id | The id of that owner on the forge. |
ref | The 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_ref | Pull request runs only: the name of the head branch, like feature. |
sha | The commit that the run tests. |
event | push, pull_request, schedule, manual or after. |
workflow | The name of the workflow, from defineWorkflow. |
job | The name of the job. |
run_id | The id of the run. |
actor | The user name of the person that the job acts for, or system. |
actor_id | The id of that person on the forge, or system. |
trust | trusted or protected. |
workflow_ref | <owner>/<repo>/<workflow file>@<ref>, like acme/app/.source/workflows/deploy.ts@refs/heads/main. |
job_workflow_ref | The same as workflow_ref. |
runner_environment | Always 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.