Skip to content

Hairspring in CI

Tom Barber edited this page Nov 5, 2026 · 1 revision

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.

Where each kind of target can run

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

The exit codes

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.

A GitHub Actions workflow

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-atomic

The 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.

Reproduce a CI failure on your own machine

Download the hairspring-results artifact, then replay the bundle from a checkout of the commit CI ran:

hairspring replay .hairspring/bundles/pubsub-buggy-3893b41f.hairspring

It 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/.

Other CI systems, and process targets

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.

What was not run

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.

Clone this wiki locally