Skills, MCP and apps / Apps and webhooks
Trust a CI job
Your app takes uploads from CI jobs, like a package build to publish as a preview. It must know which repository, commit and pull request each upload comes from.
4 min read
A shared secret in the job can leak, and the pull request of a fork can copy it. A job identity token solves this.
A job that names your app sends a token, signed by Source, with the facts of the run. Your app checks the signature with the public keys of Source. The job never holds the token: it holds only a placeholder, and Source puts the token into the request on its way out.
You need:
- An app that you registered. See Build an app.
1. Set the hosts and the lowest trust
On /settings/apps/<slug>:
- In Job token hosts, type the host names of your upload API, one a line, at most 10. For example,
upload.example.com. A token goes only to these hosts. - In Minimum trust, pick the lowest trust level of a run that gets a token:
untrusted,trustedorprotected. A run below it gets no token. - Save.
2. Tell the workflow authors
The author of a workflow names your app on a job, and lists your hosts in the egress of the job. Send them to Use an app from a CI job.
For your app, the variable of the job is SOURCE_APP_TOKEN_<SLUG>: your slug in upper case, with _ for -. Tell the authors which header to put it in, for example:
curl -X POST https://upload.example.com/upload \
-H "Authorization: Bearer $SOURCE_APP_TOKEN_HELLO_APP" \
--data-binary @package.tgz
3. Check the token
The public keys are at https://source.tanstack.com/oidc/jwks. This check uses only WebCrypto, so it runs in Cloudflare Workers, Deno, Bun and Node 20 or later:
const ISSUER = 'https://source.tanstack.com/oidc'
const JWKS_URL = `${ISSUER}/jwks`
const RS256 = { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }
export interface JobClaims {
iss: string
aud: string
kind: 'app'
app: string
appId: string
sub: string
repo: string
repoId: string
ref: string
sha: string
pull: number | null
run: string
job: string
workflow: string
trust: 'untrusted' | 'trusted' | 'protected'
fork: boolean
iat: number
exp: number
jti: string
}
const encoder = new TextEncoder()
const decoder = new TextDecoder()
const fromBase64url = (text: string) => Uint8Array.from(atob(text.replace(/-/g, '+').replace(/_/g, '/')), (char) => char.charCodeAt(0))
const partOf = (text: string) => JSON.parse(decoder.decode(fromBase64url(text)))
/** The claims of `token` when Source signed it for app `slug` and it has not ended. Throws otherwise. */
export async function verifyJobToken(token: string, slug: string): Promise<JobClaims> {
const [head, body, signature] = token.split('.')
if (!head || !body || !signature) throw new Error('This is not a JWT')
const header = partOf(head) as { alg: string; kid: string }
if (header.alg !== 'RS256') throw new Error('The token is not RS256')
const jwks = (await (await fetch(JWKS_URL)).json()) as { keys: (JsonWebKey & { kid: string })[] }
const jwk = jwks.keys.find((key) => key.kid === header.kid)
if (jwk === undefined) throw new Error('The key of the token is unknown')
const key = await crypto.subtle.importKey('jwk', jwk, RS256, false, ['verify'])
const isValid = await crypto.subtle.verify(RS256.name, key, fromBase64url(signature), encoder.encode(`${head}.${body}`))
if (!isValid) throw new Error('The signature is wrong')
const claims = partOf(body) as JobClaims
if (claims.iss !== ISSUER) throw new Error('The token is from another issuer')
if (claims.aud !== `source-app:${slug}` || claims.kind !== 'app') throw new Error('The token is not an app token for this app')
if (claims.exp <= Math.floor(Date.now() / 1000)) throw new Error('The token has ended')
return claims
}
Use it in your upload route:
const token = request.headers.get('authorization')?.replace(/^Bearer /, '') ?? ''
const claims = await verifyJobToken(token, 'hello-app').catch(() => null)
if (claims === null) return new Response('The job token is refused', { status: 401 })
// claims.repo, claims.sha and claims.pull say where the upload comes from.
- Always check
audandkind. A token for another app, or the OIDC token of a job, must not work on yours. - Decide what a fork can do.
fork: trueruns get a token too, when the workflow of the base branch names your app. - If a repeat of one request must fail, keep the
jtiof each token that you took for 10 minutes. - Source lets the
/oidc/jwksanswer be cached for 5 minutes. When you get many uploads, cache it on your side too.
What works now
- A CI job sends your app a signed token that says which repository, commit, pull request and run it comes from.
- Your app checks it with the public keys of Source, with no shared secret.
- Runs below your lowest trust get no token, and no token goes to a host that you did not list.
Who gets a token
Source gives a job a token for your app only when all of these hold:
- Your app is installed on the repository of the job, and is not suspended.
- The job names your app in the workflow of the base branch. A pull request cannot add it.
- The trust of the run is at your Minimum trust or higher.
- The egress of the job lists at least one of your Job token hosts.
- The workflow is not a hidden workflow.
The token goes only into a request header, and only to your hosts. A request that carries the placeholder in a URL, or to another host, is refused.
The token
The token is a JWT, signed with RS256. Its header names the key (kid). Source signs it with the same key as the OIDC tokens of CI jobs. But an app token never passes as an OIDC token, or the reverse: its aud and its kind are different.
Each request with the placeholder gets a new token. Its claims:
| Claim | What it is |
|---|---|
iss | https://source.tanstack.com/oidc |
aud | source-app:<slug>, like source-app:hello-app. A job's OIDC token never gets an audience of this form. |
kind | Always app. An OIDC token has no kind. |
app, appId | Your app's slug and its id. |
sub | repo:<owner>/<name>:ref:<ref>, like repo:alice/app:ref:refs/heads/main. |
repo, repoId | The repository, as owner/name, and its id. |
ref, sha | The ref and the commit of the run. |
pull | The pull request's number, or null for a run with no pull request. |
run, job, workflow | The CI run id, the job key (like test (shard: 1)) and the workflow name. |
trust | untrusted, trusted or protected. |
fork | true for a pull request whose head is in another repository. |
iat, exp | When it was made and when it ends, in seconds. It lives 10 minutes. |
jti | A new id for each token. |