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 org-side, so you only carry the
uses:link — Vivarium-side 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/.github/.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/.github/.github/workflows/vivarium-verdict.yml@main
with:
slug: bash-local-shadows-exit
pandas-issue:
uses: aletheia-works/.github/.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.