The shape of it
Every recipe has the same three parts:
- Install stoop on a Linux runner.
- Wrap the steps. In GitHub Actions one
defaultsblock does it; elsewhere, putstoop run --in front of each command. - 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_WRITEonly on the default branch. An empty value or0is off, soSTOOP_SYNC_WRITE: ${{ github.ref == 'refs/heads/main' && '1' || '' }}works; setting it from a step guarded byif:, 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(orSTOOP_SYNC=git) uses the remote namedorigin;git:NAMEpicks another.- On a miss, stoop fetches
refs/stoop/<key>for that one key and checks again.stoop pullfetches every published proof once, which is cheaper at the start of a job that runs many steps. - With
--sync-write(orSTOOP_SYNC_WRITE=1), a recorded run publishes its proofs, merged with what is already there. stoop prunedeletes 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_SALTfrom a repository secret on every job that records or checks proofs: the hashes are then keyed with it (they start withs:) 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 withstoop 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
