自分のリポジトリに統合する
// GUIDE · 統合
自分のリポジトリで Vivarium 再現を宣言・検証する。
Vivarium 本体をフォークしなくても、自分のリポジトリのルートに 1 ファイルを置き、CI ジョブを 1 つ足すだけで「私たちはこのバグの再現をホストしている」と宣言できる。アップストリーム修正の到達も同じ仕組みで自動検知される。
// 0 · 何が手に入るか
自分のリポジトリの CI に Vivarium verdict が乗る。
この統合パスでは、自分のリポジトリ（フォークではなく、ふつうのプロジェクトリポジトリ） に 2 つだけ追加します:
.vivarium/manifest.toml— Vivarium 互換再現の宣言ファイル （仕様: Manifest v1）。.github/workflows/check-bug.yml— 再利用可能 verdict ワークフロー をuses:で呼ぶだけのジョブ。
これだけで、対象のアップストリームバグが今でも再現するかどうかが、 自分の CI の green / red シグナルとして毎日（あるいは毎 PR で）勝手に検証されます。 アップストリームが修正を出荷した瞬間、CI が赤くなり、その瞬間が 「このバグはもう追跡しなくてよい」のシグナルになります。
Vivarium 本体のソースをコピーしません。再利用可能ワークフローが組織側で 保守されているので、こちらは
uses:のリンクだけ持っておけば、 Vivarium 側の改善が自動で乗ります。
// 1 · 検証したいバグを選ぶ
既存のレシピなら、すぐ使えるスラッグを 1 つ控える。
Vivarium カタログにすでに存在するバグなら、
そのスラッグ（<project>-<issue> 形式）を控えるだけで進めます。
たとえば:
bash-local-shadows-exit（Layer 2 / bash）pandas-56679（Layer 1 / pandas）
再現一覧 でファセット検索ができます。 自分が追跡しているエラーメッセージを起点にしたい場合は エラーからレシピを探す を使えば 候補がスコア順で出ます。
アップストリームでまだ再現が無いバグの場合は、自分のフォークでレシピ自体を作る ルートになります。手順は 自分のフォークで動かす に分けてあります。
// 2 · manifest.toml を作る
フォームに入れて生成、リポジトリにコピー。
対話的に埋められるフォームが マニフェスト作成 にあります。slug、layer、bug.project、bug.issue、bug.upstream_url を埋めて「生成」を押すと TOML がそのまま出ます。
生成された TOML を .vivarium/manifest.toml（リポジトリのルート直下に .vivarium ディレクトリを作る）として保存します。ファイル名・パス共に固定で、それ以外の場所では認識されません。
TOML の先頭行に #:schema https://aletheia-works.github.io/vivarium/spec/manifest.schema.json が入っているはずです（スキャフォールダが付けます）。Taplo / Tombi など TOML LSP のあるエディタは、これだけで補完と検証が効きます。
手書きしてもよく、スキャフォールダはあくまで典型形を出す道具 です。仕様の正典は Manifest v1 で、
verdict.schema.jsonも公開済みなので CI でも検証できます。
// 3 · CI に verdict ジョブを 1 つ追加する
Layer 2 / 3 は再利用可能ワークフローを uses: するだけ。
.github/workflows/check-bug.yml として以下を保存します
（slug: は手順 1 で控えたものに置き換えてください）:
name: vivarium-check
on:
pull_request:
schedule:
- cron: '17 4 * * *' # 毎日 1 回、UTC 04:17
jobs:
bash-issue:
uses: aletheia-works/.github/.github/workflows/vivarium-verdict.yml@main
with:
slug: bash-local-shadows-exit
これで ghcr.io/aletheia-works/vivarium-bash-local-shadows-exit:latest
がプルされ、レシピが実行され、Contract v1 準拠の verdict.json
がキャプチャされ、JSON Schema で検証されます。
verdict が expected_verdict（デフォルト "reproduced"）と
一致しなければジョブが赤くなります。
追跡したいバグが複数ある場合は、ジョブを並べるだけ:
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（ブラウザ内 WASM）の再現は、verdict が DOM / JavaScript ライブで決まるため、 この再利用可能ワークフローでは検証できません。Layer 1 のリグレッション検知は Vivarium 本体の Playwright スイートが既に正式な仕組みとして担当しています。 Layer 1 をマニフェストで宣言するだけは可能で、その場合
page_urlを貼り、検証はサイト側に任せる運用になります。
// 4 · 動作確認
緑が出れば「再現は今でも本物」。
上の 2 ファイル（manifest と check-bug.yml）を 1 commit にして PR を立てます。最低限のコミットメッセージは feat(ci): subscribe to bash-local-shadows-exit verdict のような形で十分です。
初回は GHCR からのイメージプルがあるので 1〜2 分かかります。完了するとジョブのアーティファクトに verdict-<slug>-<run_id> が出ます。中身が verdict.schema.json に従う JSON です。
毎日 1 回でも回しておくと、アップストリームが修正を出荷した日に CI が赤くなり、Slack / メール / GitHub の通知でその瞬間が分かります。これがアップストリーム修正検知シグナルそのものです。
赤くなったら「壊れた」ではなく「修正された」。verdict セマンティクスが テスト的な感覚と逆向きである点は、用語集の verdict と Contract v1 で改めて固定しています。
// 5 · 次の選択肢
この surface から続く線。
ブランチで書いた fix を当てた後の verdict と、当てる前の verdict を横並びで比較する surface があります: 再現を比較する。AI エージェントが書いたパッチの検証用に作られたページで、reproduced → unreproduced への反転がそのまま「修正は効いた」のシグナルになります。
再利用可能ワークフローの image: インプットでオーバーライドできます。git-sha 付きタグや、自分のフォークで Build した GHCR イメージを差し込めます。仕様: consumer workflow のインプット表。
cron 行を消して workflow_dispatch: を足せば、Actions タブから手動実行のみになります。低頻度のレシピ（年単位で動かない上流）に向いた運用です。
レシピ自体を新しく書く話なので、自分のフォークで動かす の手順から入ります。Layer 1 だけならフォーク内で完結します。
この手順がうまく動かなかった箇所は、それは integrate ガイドのバグです。 具体的にどのステップで詰まったかを Issue に残してください—— どこで詰まるかが、次のドキュメント版の優先順位を決めます。