Skip to content
Source
Sign inSign up

Trust a CI job

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:

1. Set the hosts and the lowest trust

On /settings/apps/<slug>:

  1. 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.
  2. In Minimum trust, pick the lowest trust level of a run that gets a token: untrusted, trusted or protected. A run below it gets no token.
  3. 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 aud and kind. A token for another app, or the OIDC token of a job, must not work on yours.
  • Decide what a fork can do. fork: true runs get a token too, when the workflow of the base branch names your app.
  • If a repeat of one request must fail, keep the jti of each token that you took for 10 minutes.
  • Source lets the /oidc/jwks answer 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:

ClaimWhat it is
isshttps://source.tanstack.com/oidc
audsource-app:<slug>, like source-app:hello-app. A job's OIDC token never gets an audience of this form.
kindAlways app. An OIDC token has no kind.
app, appIdYour app's slug and its id.
subrepo:<owner>/<name>:ref:<ref>, like repo:alice/app:ref:refs/heads/main.
repo, repoIdThe repository, as owner/name, and its id.
ref, shaThe ref and the commit of the run.
pullThe pull request's number, or null for a run with no pull request.
run, job, workflowThe CI run id, the job key (like test (shard: 1)) and the workflow name.
trustuntrusted, trusted or protected.
forktrue for a pull request whose head is in another repository.
iat, expWhen it was made and when it ends, in seconds. It lives 10 minutes.
jtiA new id for each token.