CI recipes

Where stoop earns its keep. Wrap the steps, then give runs a way to share what they proved.

A peregrine on the parapet of a high-rise at dawn above a hazy city.

The shape of it

Every recipe has the same three parts:

  1. Install stoop on a Linux runner.
  2. Wrap the steps. In GitHub Actions one defaults block does it; elsewhere, put stoop run -- in front of each command.
  3. Share proofs between runs. A fresh runner has an empty .stoop/, so nothing would ever skip. Either cache that directory with the CI's own cache, or sync proofs through your git remote. Pull request runs read; only the default branch writes.

Why only the default branch writes. A proof is a claim that lets later runs skip checks. Proofs written by code that hasn't been reviewed shouldn't let main skip anything. Branches read main's proofs, so a branch that matches main skips what main already proved.

Prebuilt binaries support Linux x86-64 and arm64, and macOS x86-64 and arm64. macOS runs commands untraced and records nothing.

GitHub Actions

With sync through the repository's own remote. Proofs live at refs/stoop/<key>, which branch and tag listings ignore.

name: CI
on:
  pull_request:
  push:
    branches: [main]

defaults:
  run:
    shell: stoop sh {0}       # every run: step goes through stoop

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: write          # main pushes refs/stoop/*
    env:
      STOOP_SYNC: git
    steps:
      - uses: actions/checkout@v4
      - name: Install stoop
        shell: bash               # stoop is not installed yet
        run: |
          curl -fsSL https://stoop.build/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Publish proofs from main only
        if: github.ref == 'refs/heads/main'
        shell: bash
        run: echo "STOOP_SYNC_WRITE=1" >> "$GITHUB_ENV"
      - name: Fetch published proofs
        shell: bash
        run: stoop pull
      - run: cargo fmt --check
      - run: cargo clippy --all-targets -- -D warnings
      - run: cargo test
  • Each wrapped step is keyed by its script, the workflow and the job, so the same script in two jobs gets two keys.
  • Steps that use an action (uses:) are not shell steps and run as usual.
  • Set STOOP_SYNC_WRITE only on the default branch. An empty value or 0 is off, so STOOP_SYNC_WRITE: ${{ github.ref == 'refs/heads/main' && '1' || '' }} works; setting it from a step guarded by if:, as above, is just as good.
  • Sync never fails a step. If the remote is unreachable or refuses a push, stoop warns and the step runs as it would have without sync.

Or with the Actions cache

If you'd rather not give the job push access, cache .stoop/. A run can restore caches saved on its own branch and on the default branch (GitHub's cache access rules), so save only on main:

      - uses: actions/cache/restore@v4
        with:
          path: .stoop
          key: stoop-${{ github.job }}-${{ github.run_id }}
          restore-keys: stoop-${{ github.job }}-
      # ... your run: steps ...
      - if: github.ref == 'refs/heads/main'
        uses: actions/cache/save@v4
        with:
          path: .stoop
          key: stoop-${{ github.job }}-${{ github.run_id }}

GitLab CI

GitLab keeps caches for protected and unprotected branches separate by default (GitLab caching docs), so a merge request pipeline can't read the cache main saved. Git sync is the way to share main's proofs with merge requests:

test:
  image: rust:1
  variables:
    STOOP_SYNC: git
  before_script:
    - curl -fsSL https://stoop.build/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
    - if [ "$CI_COMMIT_BRANCH" = "$CI_DEFAULT_BRANCH" ]; then export STOOP_SYNC_WRITE=1; fi
    - stoop pull
  script:
    - stoop run -- cargo test

Reading uses whatever credentials the checkout used. Publishing from main needs a token allowed to push to the repository; point a remote at it and name that remote in the spec, for example STOOP_SYNC: git:publish.

The simpler, per-branch alternative: cache .stoop/ with key: stoop-$CI_JOB_NAME-$CI_COMMIT_REF_SLUG. Each branch then reuses its own earlier pipelines' proofs, but starts cold.

CircleCI

Restore everywhere, save from main only, using a step-level when:

version: 2.1
jobs:
  test:
    docker:
      - image: rust:1
    steps:
      - checkout
      - run: curl -fsSL https://stoop.build/install.sh | sh && echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$BASH_ENV"
      - restore_cache:
          keys:
            - stoop-main-
      - run: stoop run -- cargo test
      - when:
          condition:
            equal: [ main, << pipeline.git.branch >> ]
          steps:
            - save_cache:
                key: stoop-main-{{ .Revision }}
                paths: [ .stoop ]

Or use git sync exactly as in the GitLab recipe, gating STOOP_SYNC_WRITE on CIRCLE_BRANCH.

Buildkite

Buildkite has no built-in cache on self-hosted agents, which makes git sync the natural fit: nothing to host, and the agent already talks to the remote.

steps:
  - label: ":rust: test"
    env:
      STOOP_SYNC: git
    command: |
      if [ "$BUILDKITE_BRANCH" = "$BUILDKITE_PIPELINE_DEFAULT_BRANCH" ]; then export STOOP_SYNC_WRITE=1; fi
      stoop pull
      stoop run -- cargo test

Install stoop on the agent image once. Publishing needs the agent's git credentials to allow pushes from default-branch builds.

How git sync works

  • --sync git (or STOOP_SYNC=git) uses the remote named origin; git:NAME picks another.
  • On a miss, stoop fetches refs/stoop/<key> for that one key and checks again. stoop pull fetches every published proof once, which is cheaper at the start of a job that runs many steps.
  • With --sync-write (or STOOP_SYNC_WRITE=1), a recorded run publishes its proofs, merged with what is already there.
  • stoop prune deletes published proofs older than --max-age (default 7 days). It needs write access; a scheduled job on main is the place for it.
  • Shallow checkouts are fine: the proof refs are fetched on their own.
  • Proofs record a hash of every environment variable, and published proofs are readable by anyone who can read the repository. An unsalted hash of a low-entropy value (a short token, a flag) can be guessed offline. Set STOOP_ENV_SALT from a repository secret on every job that records or checks proofs: the hashes are then keyed with it (they start with s:) and stoop warns when it publishes without one. A run without the secret, such as a pull request from a fork, cannot match a salted proof and simply runs the command. Proofs published before you set it keep their unsalted hashes until they expire or you remove them with stoop prune --max-age 0.

Tested: the sync suite runs against a bare git remote, and the ref mechanics (push, shallow fetch, delete) were checked against GitHub. Not yet verified: a full authenticated sync run inside a hosted CI provider.

The nightly full run

A file trace can't see the clock. Re-prove everything on a schedule so a test that depends on today's date can't hide behind a proof for long:

on:
  schedule:
    - cron: "17 4 * * *"
env:
  STOOP_FULL: "1"            # never skip, still record