Integrate with your own repo
// GUIDE · INTEGRATION
Declare and verify a Vivarium reproduction in your own repo.
No fork required. Drop one file at the root of your project repo and add one CI job, and you have declared 'we host a reproduction for this bug.' Upstream-fix detection rides on the same wiring.
// 0 · WHAT YOU GET
A Vivarium verdict signal in your own CI.
In this flow your project repo (not a fork of Vivarium — your normal product or library repo) gains exactly two additions:
.vivarium/manifest.toml— a declaration that says "Vivarium-compatible reproduction lives here" (spec: Manifest v1)..github/workflows/check-bug.yml— a one-job CI workflow thatuses:the reusable verdict workflow.
That's enough to make "is this upstream bug still reproducing?" a green / red signal in your own CI, on every PR or on a daily schedule. The day upstream ships a fix, the workflow turns red — and that red is your "we no longer need to track this bug" signal.
You don't copy any Vivarium source. The reusable workflow is maintained in the Vivarium repository, so you only carry the
uses:link — improvements ride along automatically.
// 1 · PICK A BUG TO TRACK
If it's already in the catalogue, just note one slug.
If the upstream bug is already in the Vivarium catalogue, jot down its slug (<project>-<issue> shape) and you're done with this step. For example:
bash-local-shadows-exit(Layer 2 / bash)pandas-56679(Layer 1 / pandas)
The faceted recipe gallery is the way to browse. If you have a concrete error message in hand, the error → recipe matcher ranks candidates for you.
If the upstream bug isn't in the catalogue yet, you're in the "build a new recipe" path instead, which is documented in Run on your own fork.
// 2 · DROP A MANIFEST
Generate it from a form, copy it into your repo.
An interactive form lives at Create a manifest. Fill in slug, layer, bug.project, bug.issue, bug.upstream_url, hit "Generate," and the TOML pops out.
Save the generated TOML as .vivarium/manifest.toml (create the .vivarium directory at the repo root). Both the directory and filename are fixed; nothing recognises the file at any other path.
The first line of the TOML should be #:schema https://aletheia-works.github.io/vivarium/spec/manifest.schema.json (the scaffolder writes it for you). Editors with a TOML language server (Taplo, Tombi) pick this up automatically and give you completion plus inline validation.
Hand-writing the manifest is fine — the scaffolder is just there to spit out the canonical shape. The authoritative spec is Manifest v1, and
verdict.schema.jsonis published, so CI-side validation is possible too.
// 3 · ADD A VERDICT JOB
Layer 2 / 3: just `uses:` the reusable workflow.
Save the following at .github/workflows/check-bug.yml (replacing slug: with the one you noted in step 1):
name: vivarium-check
on:
pull_request:
schedule:
- cron: '17 4 * * *' # once a day at 04:17 UTC
jobs:
bash-issue:
uses: aletheia-works/vivarium/.github/workflows/vivarium-verdict.yml@main
with:
slug: bash-local-shadows-exit
That pulls ghcr.io/aletheia-works/vivarium-bash-local-shadows-exit:latest, runs the recipe, captures a Contract v1 verdict.json, validates it against the published JSON Schema, and asserts the captured verdict matches expected_verdict (default "reproduced"). Anything else turns the job red.
Tracking several bugs is a matter of stacking jobs:
jobs:
bash-issue:
uses: aletheia-works/vivarium/.github/workflows/vivarium-verdict.yml@main
with:
slug: bash-local-shadows-exit
pandas-issue:
uses: aletheia-works/vivarium/.github/workflows/vivarium-verdict.yml@main
with:
slug: pandas-56679
Layer 1 (in-browser WASM) recipes can't be verified through this reusable workflow because their verdict is set live in DOM / JavaScript. The Vivarium gallery's own Playwright suite is the canonical regression check for Layer 1. You can still declare a Layer 1 manifest by pointing
page_urlat the live page; the gallery side handles verification.
// 4 · VERIFY
Green = the bug still reproduces today.
One commit holding both files (manifest plus check-bug.yml) is enough. A minimal commit message such as feat(ci): subscribe to bash-local-shadows-exit verdict is fine.
First run takes 1–2 minutes due to the GHCR image pull. On completion, the job artifact verdict-<slug>-<run_id> contains a JSON document that conforms to verdict.schema.json.
Even one run a day is enough — the day the upstream project ships a fix that no longer reproduces, your CI turns red, and that red is the upstream-fix detection signal.
Red means "fixed," not "broken." The verdict semantics flip the test-mindset direction; the glossary verdict entry and the Contract v1 page nail this down.
// 5 · WHERE TO GO NEXT
Lines that branch out from this surface.
The comparison surface lets you put the post-fix verdict next to the pre-fix one: Compare reproductions. It's the page built for AI-generated patches — a reproduced → unreproduced flip is exactly the "the fix worked" signal.
The reusable workflow takes an image: input that overrides the default. A git-sha-tagged image, a private fork build — anything in GHCR — is fair game. Reference: the input table in consumer workflow.
Drop the cron line and add workflow_dispatch: for manual-only runs. A reasonable shape for slow-moving upstream bugs that don't reward daily polling.
Then you're writing a new recipe, not consuming one. Run on your own fork covers that flow. Layer 1 is fully self-contained inside a fork.
If a step in this guide didn't work, that's a bug in this guide — file an issue with the exact step where you got stuck. Where readers get stuck sets the priority for the next docs revision.