Skip to content
hushrunDocs

In CI

In CI, hushrun skips the checks this exact code already passed anywhere, on a laptop, in an agent's sandbox or in an earlier run, and records the rest for everyone else to reuse.

GitHub Actions

CI needs no secret. When package.json names the backend, as npx hushrun init writes it, it needs no variable either. Give each job that runs a wrapped check an ID token:

.github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run lint
      - run: npm test

npm ci installs hushrun with your other devDependencies, and npm test goes through hushrun run as it does everywhere else. init adds id-token: write for you, to the job's permissions: or the workflow's. When neither has one, it adds a block with contents: read too, since a permissions: block replaces the token's defaults: add any other permission the job needs.

How CI is recognized

hushrun asks GitHub for an ID token made for your organization's backend, and the backend checks which repository the job runs for. hushrun's hosted service accepts a repository that your organization connected, which init does with your sign-in. The first result it accepts pins that repository's GitHub id. A repository deleted and created again under the same name has another id, so it is refused, with a message that says why; a renamed repository keeps working.

  • Pull requests from forks get no ID token, so their checks run and nothing is recorded.
  • A job without id-token: write has no credential either. Its checks run, and its log ends with hushrun: results aren't shared with acme: … and the backend's reason.

Without package.json

For a repository without package.json, or a job that doesn't install your Node.js dependencies, install hushrun in the job and name the backend there:

.github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    env:
      HUSHRUN_BACKEND: https://api.hushrun.com/o/acme
    steps:
      - uses: actions/checkout@v4
      - run: npm install --global hushrun
      - run: hushrun run unit -- cargo test

Your organization's URL is in hushrun whoami on a signed-in machine.

CI reuses only CI's results

By default, CI skips a check that a laptop or an agent already passed on the same files. An admin can stop that for one repository: on its settings page in the dashboard, turn on CI reuses only CI's results. CI then skips a check only on passes CI itself recorded, while passes from laptops and agents still speed up people and agents. hushrun says so on each line:

hushrun: unit skipped: this exact code passed in CI 3 min ago (saves 41s); skipped only on CI's passes
hushrun: unit running: no CI pass yet for this exact code; skipped only on CI's passes

The server enforces it; nothing in the repository can turn it off.

Other CI

GitLab CI, CircleCI, Buildkite, Jenkins and the rest record with an agent token and the key it comes with. An organization admin creates them, signed in with hushrun login, in the repository:

hushrun token create --agent gitlab-ci --expires 365d

It prints the token and the key once. Store the token as a masked, protected secret named HUSHRUN_TOKEN in the CI's settings, and the key, the whole PEM block, as a protected secret named HUSHRUN_MACHINE_KEY. Where the CI can't mask a value of several lines, as on GitLab, store the key as a File variable named HUSHRUN_MACHINE_KEY_FILE instead: GitLab writes it to a file and sets the variable to the file's path. Then run the checks as usual:

.gitlab-ci.yml
test:
  image: node:22
  script:
    - npm ci
    - npm test
  • The token records and reads results for that one repository, as agent:gitlab-ci. --org-wide makes one for every repository of the organization.
  • The results it records carry the key's signature: without the key, checks still run, but their results aren't recorded.
  • It expires after 30 days unless --expires says otherwise, 365 days at most. Before it does, create the next one under the same name, update both secrets, and revoke the old one with hushrun token revoke.
  • An agent token follows package.json's backend only on hushrun's hosted service. For a backend on another server, set HUSHRUN_BACKEND in the job too.

The dashboard's Agents page creates the same tokens, each with its key, and lists and revokes them. Agents and sandboxes has the details, which apply to CI too.

Markdown