自分のフォークで動かす
// GUIDE · フォーク運用
自分のフォークで Vivarium を動かす。
このリポジトリをフォークして、自分のバグ再現を自分の GitHub Pages に公開する手順。アップストリームに PR を投げなくても、自分自身のリポジトリで再現を整え、URL でシェアできる。
// 0 · 何ができるか
自分の <user>.github.io/vivarium/ に自分のバグ再現を並べる。
この使い方では、ユーザーは aletheia-works/vivarium をフォークし、
自分のフォークリポジトリの上で再現レシピを足したり編集したりして、
自分の GitHub Pages サイトとして公開します。アップストリームに
contribute するのではなく、自分のフォーク自体が公開先
になります。
Layer 1（ブラウザ内 WASM）は完全にあなたのフォーク側で完結します。 Layer 2 / 3（Docker・record-replay）はアップストリームの GHCR イメージと統合された配信が前提なので、フォークでは Layer 1 のみ が deploy されます。
アップストリームの再現一覧と並べる予定がない、自分専用の再現置き場として 使う運用を想定しています。共有したいときは
https://<あなた>.github.io/vivarium/の URL を渡すだけです。
// 1 · リポジトリをフォークする
GitHub の UI から 1 クリック。
aletheia-works/vivarium 右上の
Fork ボタンから自分のアカウント（または組織）配下にフォークします。
リポジトリ名は vivarium のままでも、別名でも構いません（別名にした場合は
この手順書の vivarium 部分を読み替えてください）。
その後ローカルにクローンします:
git clone https://github.com/<あなた>/vivarium.git
cd vivarium// 2 · ツールチェーンを揃える
mise が一括で入れる。
このプロジェクトは mise でツールバージョンを管理しています。 クローン直下で:
mise installこれで bun（docs/MCP サーバ用）、opentofu（GitHub 設定の
Infrastructure-as-Code 用）、uv（Python ネイティブ再検証用）等が揃います。
レシピを追加する Layer / 言語によっては Rust ツールチェイン（rustup）も必要です。
// 3 · Fine-grained PAT を発行する
OpenTofu がフォークの設定を読み書きするためのトークン。
Settings → Developer settings → Personal access tokens → Fine-grained
から、自分のフォークリポジトリ宛のトークンを発行します。
- Resource owner: 自分のアカウント（または組織）
- Repository access: フォークしたリポジトリのみ
- Repository permissions: Administration (RW), Contents (RW), Metadata (R), Issues (RW), Pull requests (RW), Actions (RW), Workflows (RW), Variables (RW), Webhooks (RW)
トークン値は絶対にコミットしないでください。
terraform.tfvarsもリポジトリの.gitignoreに登録済みです。
// 4 · OpenTofu でフォーク側のリポジトリ設定を整える
ラベル、Pages、ブランチ保護を一括反映。
cp infra/github/terraform.tfvars.example infra/github/terraform.tfvars してから、github_owner = "<あなた>" に書き換えます。create_phase_milestones は false（デフォルト）のままでよく、Phase マイルストーンはアップストリーム専用なのでフォークでは作成されません。
export GITHUB_TOKEN=github_pat_xxxxxxxx。シェルが閉じれば消えます。
cd infra/github && tofu init && tofu plan の出力を確認した上で tofu apply。Pages の有効化、ラベル、ブランチ保護がフォーク側に反映されます。
// 5 · GitHub Pages のデプロイを有効にする
リポジトリ変数を 1 つ足すだけ。
フォークでは GitHub Pages へのデプロイはデフォルトで止めてあります
（.github/workflows/deploy-docs.yml の if 条件によるもの）。
フォークの所有者として deploy を有効化したい場合は、リポジトリ変数を 1 つ足します。
"Variables" タブを選びます（"Secrets" ではありません）。
Name: VIVARIUM_FORK_DEPLOY、Value: true。
Actions タブ → Deploy docs to GitHub Pages → Run workflow から手動でも起動できます。
この変数を後で消せば、deploy は再びスキップされます。 Layer 2（Docker / GHCR）はフォークの権限ではプッシュできないため、 フォーク deploy では自動的に Layer 1 のみがバンドルされます。
// 6 · 自分のレシピを追加する
src/layer1_wasm/<slug>/ にディレクトリを 1 つ。
Layer 1 レシピの最小単位は、再現したい上流バグごとに 1 つのディレクトリです:
src/layer1_wasm/<slug>/index.html— レシピページの骨格src/layer1_wasm/<slug>/repro.ts— Pyodide / Ruby.wasm / php-wasm / Rust などで再現スクリプトを実行し、verdict を設定src/layer1_wasm/<slug>/README.md— レシピの説明
既存の pandas-56679
や regex-779 を雛形にコピーして、
上流バグの slug（<project>-<issue> 推奨）と
再現スクリプトを書き換えるのが最短です。
レシピが satisfy するべき仕様は Contract v1 に書かれています。
<meta name="vivarium-contract" content="v1">とdata-verdict="reproduced|unreproduced|pending"の#verdict要素を出力すれば、自動的に整合します。
// 7 · push して deploy を確認
自分の Pages URL でレシピを開く。
レシピを main にプッシュすると、VIVARIUM_FORK_DEPLOY=true
が設定されたフォークでは deploy-docs ワークフローが走ります。完了後、
以下の URL でサイトが見えます:
https://<あなた>.github.io/vivarium/個別レシピは /repro/<project>/<issue>/ 以下に配置されます。
この URL は recipes.json 生成時に GITHUB_REPOSITORY_OWNER /
GITHUB_REPOSITORY から動的に組み立てられるため、フォークでも
ハードコード書き換えなしで正しい URL が出力されます。
// 8 · 共有する
URL を渡すだけ。
自分のフォーク URL（https://<あなた>.github.io/vivarium/）を Issue
/ PR / 社内チャットで共有すれば、相手はブラウザを開くだけで再現を確認できます。
Vivarium のレシピは Contract v1 に従っているので、AI エージェントを含む第三者ツールが
verdict を機械的に読むこともできます。
アップストリームに re-publish したくなったら、自分のフォークで作ったレシピディレクトリを そのまま PR にして
aletheia-works/vivariumに投げられます。仕様（Contract v1） が同じなので、フォーク時代の verdict はそのまま意味を持ちます。