CI / Secrets and trust
Use an app from a CI job
A service that takes your uploads, like a preview registry, must know which repository and commit each upload comes from. Name the app of the service on the job: the forge swaps a placeholder for a signed job identity token as the request leaves the job.
3 min read
A secret token in the job can leak, and a pull request from a fork can try to use it. With an app, the job never holds the token.
You need:
- The app installed on the repository. See Install an app.
- The host names that the app takes uploads on, from its docs.
1. Name the app on the job
In this example, the slug of the app is pkg-preview, and it takes uploads at upload.pkg-preview.dev:
import { defineWorkflow, pullRequest, setup } from '@tanstack-source/ci'
export default defineWorkflow('preview', { on: [pullRequest()] }).job('publish', {
apps: ['pkg-preview'],
egress: ['registry.npmjs.org', 'upload.pkg-preview.dev'],
steps: [
setup.pnpm(),
{ name: 'Install', run: 'pnpm install --frozen-lockfile' },
{ name: 'Pack', run: 'pnpm pack --pack-destination out' },
{
name: 'Upload',
run: 'curl -fsS -X POST https://upload.pkg-preview.dev/upload -H "Authorization: Bearer $SOURCE_APP_TOKEN_PKG_PREVIEW" --data-binary @$(ls out/*.tgz)',
},
],
})
apps: the slugs of the apps, at most 10, each once.egress: must list the host of the app. The token goes only to the hosts that the app set and the egress of the job lists.SOURCE_APP_TOKEN_<SLUG>: the variable of each app. The slug is in upper case, with_for-.
2. Push it to the default branch
- Push the workflow to the default branch.
- Open a pull request.
A pull request run takes apps and egress from the workflow of the base branch. A pull request that adds an app gets no token for it until the change is merged. So a pull request from a fork cannot add an app to a job.
3. Send the variable in a header
The variable holds a placeholder. The forge swaps it for a fresh token only in a request header, and only to the hosts of the app:
- In a header to an app host: the app gets the signed token.
- In a URL or a query string: the request is refused.
- In a request to any other host: the request is refused.
Each request gets a new token, good for 10 minutes. The app reads which repository, commit, pull request and run the request comes from. See Trust a CI job.
Done
The job uploads to the app with a token that proves where the upload comes from. A log or a step that prints the variable shows only the placeholder.
- The job never holds the token.
- Only the base branch decides which apps the jobs of a pull request talk to.
When the job gets no variable
The job gets no SOURCE_APP_TOKEN_<SLUG> when:
- The app is not installed on the repository, or is suspended.
- The trust level of the run is below the lowest trust of the app.
- The egress of the job lists none of the hosts of the app.
- The workflow is a hidden workflow.
A run of a pull request from a fork can get the token too. It gets it when the workflow of the base branch names the app, and the trust is high enough. Its token says fork: true.