Skip to content
Source
Sign inSign up

Use an app from a job

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

  1. Push the workflow to the default branch.
  2. 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.