Repository navigation
Hairspring in CI
Run hairspring test on every push or pull request, so that a property violation fails the build and leaves behind a
bundle that anyone can replay. This page is the short version. The repository's docs/ci.md is the reference: complete workflows, the sweep flags, a job for systems other than GitHub Actions, and the list of what was and was not run.
Read Installation and Your-First-Run first. The words target, seed, bundle and sweep are in Concepts-and-Vocabulary.
| Target kind | Where it can run in CI |
|---|---|
sim (the built-in demos, or a state machine you wrote) and wasm
|
A GitHub-hosted runner, or any Linux x86-64 or macOS arm64 machine, with the release binary |
process |
A bare-metal Linux x86-64 machine you control, with Hermit and performance counters, as a self-hosted runner. GitHub-hosted runners were not tested for these |
hairspring test exits 0 when every property held on the seeds it ran, 1 when a property was violated, and 2
on an error (an unknown target, a bad flag, a missing Hermit). Every CI system fails the job on a non-zero exit, so
nothing more is needed to make a violation fail the build. A pass says only that those seeds did not fail.
Save this as .github/workflows/hairspring.yml next to a hairspring.toml. Replace <full commit sha> with the
40-character commit of the Hairspring repository you chose to use: pin by commit, not by tag or branch, because a tag
or branch can be moved after you reviewed it.
name: hairspring
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
hairspring:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write # lets the SARIF upload create code-scanning alerts
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: spiculedata/hairspring/integrations/github-action@<full commit sha>
with:
targets: lock-lease pubsub-atomicThe action downloads the release binary, checks its sha256 against the release's SHA256SUMS, runs hairspring test
once, uploads the findings to code scanning as SARIF, uploads the bundles and the report as an artifact called
hairspring-results, and fails the job on a violation. The seed defaults to the workflow run number and is printed in
the log as hairspring seed: N. Add format: junit for a JUnit report instead of SARIF.
For a regression sweep over a fixed range of seeds, add sweep: "true" and seeds: 100..200 (the end is not run, so
that is 100 trials). The job fails when any seed violates a property.
Download the hairspring-results artifact, then replay the bundle from a checkout of the commit CI ran:
hairspring replay .hairspring/bundles/pubsub-buggy-3893b41f.hairspringIt ends with reproduced: the property is still violated and exits 1. Do not rerun a red job hoping it goes green:
replay its bundle, or run hairspring test <target> --seed N with the seed from the log. Do not commit .hairspring/.
Any CI system can run the same commands: download the binary, check it with
grep hairspring-linux-x86_64 SHA256SUMS | sha256sum -c (on macOS, shasum -a 256 -c), run hairspring test ... --format junit > report.xml
and keep the report and .hairspring/bundles/ even when the job fails. The repository page has the script.
For process targets, use runs-on: [self-hosted, linux, x64] on a machine where bash scripts/install-hermit.sh check
passes and Hermit is installed. See Running-Your-Own-Software and Installation.
The workflows were checked with actionlint and the shell steps were run on a Mac against the real release, but no
workflow was run on GitHub: the code-scanning upload, the artifact upload and GitHub-hosted runners are untested. Nothing
here was run on Linux x86-64 with Hermit.
Understand
- What-is-Hairspring
- Concepts-and-Vocabulary
- How-Deterministic-Simulation-Works
- Sweeps-and-Confirmation
- Limits-and-Honesty
Use
- Installation
- Your-First-Run
- Running-Your-Own-Software
- Guest-SDKs-by-Language
- Examples-Overview
- Hairspring-in-CI
- Operate-a-Server
- Upgrading-and-Versions
- Troubleshooting
Reference