Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

リリース手順書

暫定的な手動プロセス。 このランブックでは、release-stable-manual.yml を使用して本日安定版リリースを公開する方法について説明します。これは release-plz が導入されて置き換えられるまで有効なプロセスとして残ります。その移行はまだ行われていません（今後の方向性を参照）。

ここにあるものが何か重く感じられるとしても、それは意図的な摩擦です。私たちにはまだ、それを安全に取り除けるだけの自動化の規律がありません。

最終確認は v0.8.2 リリースサイクルに対して行われました。

7つのステップで進めるプロセス

  1. changelog スキルを使用して CHANGELOG-next.md を生成する
  2. バージョンアップのPRを開いてマージする
  3. リリースワークフローを act でローカルにドライラン実行する
  4. 手動ディスパッチでRelease Stableワークフローをトリガーする
  5. プロンプトが表示されたら2つの環境ゲートを承認する
  6. リリースが存在し、アセットがダウンロード可能であることを検証する
  7. バージョン管理されたドキュメントのデプロイ

これがプロセス全体です。それ以外（crates.io、Docker、ウェブサイトの再デプロイ、Scoop、AUR、Discord、ツイート）は、下流ジョブとして自動的に実行されます。Homebrew Core は独自の autobump サービスを通じて安定版の GitHub リリースを検出します。ジョブが明示的に失敗するか、Homebrew の外部 bump が古いままになっている場合を除き、これらについて何かする必要はありません。

ステップ1: CHANGELOG-next.md を生成する

changelog-generation スキルを実行して CHANGELOG-next.md を生成します。その完全な手順は .claude/skills/changelog-generation/SKILL.md にあります。

このスキルは、最後の安定版タグから HEAD までの git log から changelog を生成し、GitHub GraphQL を介してコントリビューターを解決して、ファイルを書き込みます。結果を短命なブランチに直接コミットして、バージョン引き上げ PR（ステップ 2）に含めるか、差分が大きい場合は別の先行 PR として開いてください。

以前に中断したリリースサイクルで CHANGELOG-next.md がすでに存在する場合は、再利用する前に内容が正確かどうか確認してください。

ステップ2: バージョンPRをバンプしてマージする

ワークスペースの Cargo.toml で workspace.package.version をバンプし、その後 2 つのリリーススクリプトを順番に実行します。まずリポジトリ全体のすべてのバージョン参照を同期します:

sh

./scripts/release/bump-version.sh    # Cargo.toml からのバージョン

README のバッジ、Tauri の設定、ワークフローの説明例を更新し、cargo generate installers を介して仕様駆動のすべてのインストール対象を再生成します: install.sh、setup.bat、dist/aur/PKGBUILD、dist/aur/.SRCINFO、dist/scoop/zeroclaw.json、flake.nix、Dockerfile/Containerfile の機能セット、dev/ci/docker-tags.toml、docs/book/src/_snippets/install.md、README/プラットフォームドキュメント内の Unix 高速パスブロック、docs/book/src/setup/windows.md 内の Windows プレビルドブロック。バージョン、機能、アプリケーションパッケージングの値は Cargo.toml と [package.metadata.zeroclaw] から取得され、4 つの安定したインストール経路は xtask/src/generate/spec.rs の型付きコントラクトから取得されます。この更新により、これらの対象は自動的に同期されるため、生成領域を手動で編集しないでください。実際のリリースの提供状況は引き続き手動で記述され、ジェネレーターによって推測されることはありません。このスクリプトは、scripts/dev/refresh-nix-hashes.sh を介して Nix の git 依存関係ハッシュ（nix/hashes.json）も更新します。

翻訳を更新してピン留めする

bump-version.sh がリリースバージョンを設定した後、ドキュメント翻訳カタログを更新し、対応するタグに固定します。カタログを別途準備した場合は、タグを作成する前にカバレッジを確認し、検証してください。

cargo mdbook stats
cargo mdbook check

次に、リリースラッパーを実行します:

sh

./scripts/release/refresh-translations.sh --model-provider anthropic.release

refresh-translations.sh は Cargo.toml からバージョンを読み取り（手入力は不要）、翻訳処理を実行し、カタログを zeroclaw-labs/zeroclaw-docs-translations サブモジュールにコミットしてプッシュし、そこで v{version} タグを作成し、そのタグに固定されたメインリポジトリの gitlink をステージします。サブモジュールがまだチェックアウトされていない場合は初期化します。読み取られる Cargo.toml のバージョンがリリースバージョンになるよう、bump-version.sh の後に実行してください。リリースがハードコードされたバックエンドに依存しないよう、設定済みのプロバイダーエイリアスを明示的に指定する必要があります。必要に応じて --config-dir を渡してください。--model-provider で選択したエイリアスは providers.models.<kind>.<alias> から解決されます。カタログがすでに最新の場合は --no-translate を使用するか、Cargo.toml のデフォルトを上書きするために --model-provider の前に明示的なバージョンを渡します。例：

./scripts/release/refresh-translations.sh 0.8.2 --model-provider anthropic.release

すべてをまとめてコミット:

chore: bump version to vX.Y.Z

PR が [workspace.package] rust-version またはピン留めされた Rust ツールチェーンも変更する場合は、単なるリリースの配管ではなく、互換性の変更として扱ってください。PR では新しい MSRV を明記し、ソースビルドのアップグレードパスを説明し、CI、Docker、インストーラー、および生成されたサーフェスがマージ前に新しい下限で一致していることを示してください。

PRを作成します。type:ci、size:XS、およびPR labelerが追加するすべてのパスラベルを付けます。PRによってツールチェーンの最低要件が引き上げられる場合は、risk:highも付け、lane Dに回します。Core Teamによる独立した承認を2件取得します。CIがグリーンになった場合にのみマージします。CIのInstaller Driftゲートは、生成されたサーフェスが仕様と同期していない場合にPRを失敗扱いにするため、再生成漏れのあるPRはマージできません。Validate Translations Pinゲートは、ピン留めされたコミットでサブモジュールを解決し、カタログ形式とmsgidの整合性を検証するため、不正なピンのPRも同様にマージできません。翻訳パイプラインの詳細については、Docs & Translationsを参照してください。

マージが正しく適用されたことを確認します:

sh

git fetch origin
git show origin/master:Cargo.toml | grep '^version'
# 表示する必要があります: version = "X.Y.Z"

ステップ3: act を使ってローカルでリリースワークフローをドライランする

Release Stable ワークフローは GitHub Actions のジョブグラフであり、Run workflow をクリックした瞬間に環境ゲートの承認ウィンドウを消費します。ワークフローのステップに不備がある場合（ビルドアーティファクトの欠落、古いパス、誰かが CI を更新せずに削除した codegen ステップなど）、その失敗が表面化するのは、すでにリリースウィンドウにコミットした 後 であり、バージョン PR はすでにマージされ、master は新しいバージョンになっています。復旧には、緊急修正ブランチをマージし、CI を再実行し、すでに完全リリース版として自身を宣伝しているツリー上で、時間的プレッシャーの中で出荷することが必要になります。

これに対する安価な保険は、GitHub Actionsのフォームを開く前に、まったく同じマージ済みのmasterコミット上で、同じジョブグラフをローカルで先に実行することです。actは、GitHubが使用しているのと同じactions/*エコシステムを使って、Dockerコンテナ内でGitHub Actionsのワークフローを実行します。これはクラウドランナーを完全に再現するものではなく、アーティファクトアップロードランタイム、GitHubが発行するOIDCトークン、環境シークレット、実際のリリースタグに依存するジョブにはアクセスできませんが、これまで遭遇したほぼすべてのリリース時CI失敗の原因となるビルドおよびテストのステップは実行します。

このステップはリリースごとに15〜20分の投資となります。通常のPRごとのCIでは表面化しなかった実際の不具合を検出してきました（失敗するワークフローはpushではなくworkflow_dispatchでのみ実行されるためです）。

1回限りのセットアップ

act はワークフローを実行します。最もクリーンなインストール方法は GitHub CLI 拡張機能です。これは gh 認証を継承し、すべてのワークフロー実行に実際の GITHUB_TOKEN を公開するためです：

  1. GitHub CLI を https://cli.github.com からインストールしてください（Linux、macOS、Windows 対応）。一度だけ認証を行います: gh auth login。

  2. act 拡張機能をインストールします:

    sh

    gh extension install nektos/gh-act

    アーティファクトを生成するジョブでは、actions/upload-artifact v7 と actions/download-artifact v8 が必要とする act のアーティファクトサービスプロトコルが必要ですが、現在リリースされている act のバージョンにはそれを実装したものはありません（本稿執筆時点の最新リリースまで確認済みです）。このヘルパーは、固定されたアーティファクトアクションを使用するジョブを開始する前に、インストール済みの act バージョンを事前チェックし、安全側に倒して停止します。検証されていないバージョンではジョブを実行しません。互換性のある act リリースが公開され、実際のアーティファクトの往復処理で検証されるまで、アーティファクトを生成または消費するすべてのジョブでは、以下の GitHub-hosted フォールバックを使用してください。これは、まれな例外ではなく、現時点で推奨される方法です。

  3. https://docs.docker.com/engine/install/ から Docker Engine または Docker Desktop をインストールします。Linux では、sudo を使わずに済むように自分自身を docker グループに追加してください。act は Podman および Colima でも動作します。act runners のドキュメントを参照してください。

以上がセットアップのすべてです。それ以外（ランナーイメージ、シークレットファイル、アーティファクトサーバー、アクション SHA の事前取得）は、リポジトリの .actrc と scripts/dev/act-local.sh が処理します。

リリースごとのドライラン

ステップ2のマージされたmasterの最新状態と作業ツリーが一致していることを確認してください:

sh

git fetch upstream
git checkout upstream/master

すべてのワークフローファイルで実行可能なものを一覧表示します:

sh

./scripts/dev/act-local.sh --list

特定のジョブを実行するか、対話的に選択するか、またはドライラン可能なすべてのジョブを実行します：

sh

./scripts/dev/act-local.sh release-stable-manual:web   # 1つのジョブ
./scripts/dev/act-local.sh                              # インタラクティブピッカー
./scripts/dev/act-local.sh --all                        # すべての dry-run-safe ジョブ

最初の実行ではランナーイメージ（約1.5 GB）を取得し、Swatinem/rust-cache を通じてRustのビルドキャッシュを準備します。それ以降の実行は大幅に速くなります。このスクリプトはgitignore対象の .secrets ファイルを自動作成し、ピン留めされたすべてのアクションSHAを ~/.cache/act/ に事前取得し（そうしないと、actの浅いクローンでは任意のコミットを解決できません）、親プロセス環境を介して gh 認証からの GITHUB_TOKEN を実行にスレッド渡しし（トークン値がargvに残ることはありません）、--artifact-server-path を設定して actions/upload-artifact と actions/download-artifact がジョブ間で機能するようにします。これらはすべて、内部的には単なる act であり、スクリプトはフラグの煩雑さを取り除いているだけです。

アーティファクトを生成または消費するジョブが開始される前に、ヘルパーは解決済みのスタンドアロン act または gh act のバージョンを、内部の互換性しきい値（act >= 到達不能なセンチネル、現在は 999.0.0）と照合します。このしきい値はgo install するためのバージョンではありません。リリース済みの act バージョンでこれを満たすものはなく、実際のアーティファクトのラウンドトリップがそのリリースに対して検証された場合にのみ、実在する具体的なバージョンへ移行します。現在リリースされているすべての act バージョンは、ビルド開始前の事前チェックに失敗し、GitHub-hosted Actionsを指し示します。ローカルランナーを通過させるために、ピン留めされたアーティファクトアクションをダウングレードしないでください。

--all では、最初のジョブが開始される前に、選択されたジョブセット全体について互換性がチェックされます。選択されたジョブのいずれかがアーティファクトサービスを必要とする場合、スイープはフェイルクローズドとなり（現在リリースされている act ではしきい値を満たせません）、一部のサブセットを実行せずに終了します。--all --no-allowlist も同じ互換性ポリシーに従います。

ローカルでのアーティファクトの事前チェック失敗は、たまに起きる不具合ではなく、現在リリースされているすべての act で予想されるものです。正確なコミットを GitHub にプッシュし、アーティファクトを扱うジョブの検証用フォールバックとしてホステッドワークフローを使用してください。読み取り専用のクロスプラットフォームビルドは、CLI から安全にディスパッチして監視できます：

gh workflow run cross-platform-build-manual.yml --ref <validation-branch>
gh run list --workflow cross-platform-build-manual.yml --branch <validation-branch> --limit 1
gh run watch <run-id> --exit-status

release-stable-manual.yml をドライランの代替として早期に実行しないでください。このワークフローは環境の承認後に公開を行います。バージョンポリシーによりローカルのアーティファクトジョブがスキップされたことを記録し、アーティファクトのラウンドトリップにはホスト型のクロスプラットフォームビルドを使用し、保護された stable-release の実行はステップ 4 まで残してください。

--all は、dry-run-safe な許可リスト上のジョブのみを実行します

act は GitHub の環境保護ゲートを尊重しません。メンテナーの実際の GITHUB_TOKEN が実行に組み込まれている状態では、GitHub に書き込むジョブ（gh release create を呼び出す publish、GHCR にプッシュする docker ジョブ、gh-pages を強制プッシュする docs-deploy、issue を作成する daily-audit、webhook に投稿する tweet-release や discord-release）をローカルで成功裏に呼び出すと、初回の試行で実世界の副作用が実行される可能性があります。

したがって、--all はローカルでの実行が安全であると証明されたジョブのハードコードされた許可リストを強制します。現在は release-stable-manual.yml および cross-platform-build-manual.yml のアーティファクトのみをビルドするステップ（validate、web、release-notes、build、build-desktop）が対象です。それ以外はすべて、理由をログに記録した上でスキップされます。

==> skip release-stable-manual:publish (not on dry-run-safe allowlist)
==> skip release-stable-manual:docker (not on dry-run-safe allowlist)
==> skip release-stable-manual:crates (not on dry-run-safe allowlist)
==> skip release-stable-manual:redeploy-website (not on dry-run-safe allowlist)
==> skip docs-deploy:deploy (not on dry-run-safe allowlist)
==> skip daily-audit:advisories (not on dry-run-safe allowlist)
==> skip tweet-release:tweet (not on dry-run-safe allowlist)

許可リストはフェイルクローズ方式です。リポジトリに追加された新しいワークフローは、メンテナーがレビューして安全なジョブ ID を scripts/dev/act-local.sh の DRY_RUN_SAFE_JOBS に追加するまで、変更を加える可能性があるものとして扱われます。これが重要なのは、discover_jobs がリリースワークフローだけでなく、すべての .github/workflows/*.yml を走査するためです。拒否リスト方式では、将来の書き込みを伴うワークフローを気付かないうちに通過させてしまう恐れがあります。

ローカルで許可リストにないジョブを実行する理由がある稀なケースのために、2つのエスケープハッチが用意されています:

  • ./scripts/dev/act-local.sh release-stable-manual:publish: 明示的な <wf>:<job> 形式は指定したものを実行し、ターゲットが許可リストにない場合は act を呼び出す前に目立つ警告を表示します。
  • ./scripts/dev/act-local.sh --all --no-allowlist: --all の実行全体に対して許可リストフィルターを無効にします（ワークフローのステップがミューテーション領域に到達しないことを既に確認済みの場合にのみ使用します。例えば、実際のレジストリ認証情報を持たないフォーク上で、.secrets ファイルが空の場合など）。

actで失敗が想定されるもの（問題ありません）

act は GitHub 特有のいくつかの機能をシミュレートできません。これらの失敗は実際の不具合ではありません:

  • 実際のリリースタグに依存するジョブ（publish が GitHub Release を作成する）。
  • 環境ゲート付きジョブ（publish、docker、および crates publisher）：承認 UI はローカルには存在しません。
  • OIDC ベースのフェデレーション ID トークン。

その他のすべて、tsc エラー、ファイルの欠落、Rust のコンパイル失敗、cargo のロックファイルの不一致は、実際の不具合です。これらが master から分岐した標準的な PR で修正されるまで、GitHub Actions フォームの Run workflow をクリックしないでください。

ステップ 4: リリースをトリガーする

移動先:

https://github.com/zeroclaw-labs/zeroclaw/actions/workflows/release-stable-manual.ymlRun workflow をクリックします。次の項目を入力してください。

  • ブランチ: master
  • リリースする安定版バージョン: X.Y.Z、v プレフィックスなし

Run workflow をクリックします。

最初のジョブ（validate）は、バージョンが Cargo.toml と一致していること、および vX.Y.Z タグがまだ存在していないことを確認します。失敗した場合は、不一致を修正して再実行してください。回避策を試みないでください。

ステップ 5: 環境ゲートを承認する

3 つのジョブは GitHub 環境保護ルールによって承認待ちになります。それぞれが保留中になると、ワークフローの実行に “Waiting for review” バナーが表示されます。

3 つすべてが表示されたら承認してください。crates-io は、トークンなしのパッケージ事前チェックが正常に完了してから承認してください：

環境ジョブ何をするものか
github-releasespublishGitHub リリースを作成してアセットをアップロードします
dockerdockerイメージを GHCR にプッシュします
crates-iocrates / crates.io に公開検証済みの23クレートのワークスペースを依存関係順に公開します

承認ウィンドウを逃してジョブがタイムアウトした場合は、ワークフロー実行ページから失敗したジョブのみを再実行してください。最初からやり直す必要はありません。

ステップ6: リリースの検証

publish が完了したら、以下を確認してください:

[ ] GitHub Release exists at /releases/tag/vX.Y.Z and is marked Latest
[ ] Release notes are non-empty
[ ] SHA256SUMS asset is present and non-empty
[ ] Both SPDX and CycloneDX SBOM assets are present
[ ] Exactly one zeroclaw-vX.Y.Z-verification.tar.gz asset is present
[ ] No loose *.bundle, *.attestation.jsonl, or *.intoto.jsonl assets are present
[ ] At least one binary archive is downloadable (spot-check linux x86_64)
[ ] Prebuilt Docker and generated Docker matrix jobs are green

リリース後、CHANGELOG-next.md は意図的に master に残されます。publish ジョブはこれをリリース本文として読み取るだけで、削除はしません。次のリリースサイクルで上書きされるため、手動でのクリーンアップは不要です。

通常の workflow_dispatch 経路では、Docker Publish は安定版リリースワークフロー内で同期的に実行されます。すべてのリリースジョブが成功していれば、Docker を個別に確認する必要はありません。メンテナーが代わりに vX.Y.Z タグをプッシュしてリリースを開始した場合、Docker Publish はタグによってトリガーされた別の実行として開始されます。コンテナーの公開が完了したと判断する前に、その関連する実行が成功していることを確認してください。crates.io、Scoop、AUR について個別に対応する必要があるのは、それぞれのジョブが失敗している場合だけです。Homebrew Core はこのワークフローの対象外です。その autobump service は、対象となる formulae を独自のスケジュールで確認します。

公開されたアーティファクトの署名、SBOM、または SLSA プロベナンスを検証したいコンシューマーは、リリースアーティファクトの検証 に従うことができます。

release-attestation ワークフローに変更を加えた後は、追跡用 issue を閉じる前に、人間のメンテナーが docs/maintainers/release-attestation-runbook.md にあるオンラインおよび切断状態での検証リハーサルも実行する必要があります。ローカルでのワークフロー lint や act の実行は、そのリリースレベルのチェックの代替にはなりません。どちらも GitHub の本番 OIDC 証明を発行できないためです。

ステップ 7: バージョン管理されたドキュメントのデプロイ

ZeroClaw のドキュメントは、gh-pages ブランチ上でバージョン管理された構造を使用します。Release Stable ワークフローの deploy-docs ジョブは、publish が成功すると、そのリリースタグに対して Deploy mdBook docs to Pages ワークフローをディスパッチします。ディスパッチされた実行は、そのバージョンのドキュメントを非同期にビルドして /vX.Y.Z/ に公開します（ディスパッチジョブはそれを待ちません）。以下のブートストラップとバージョン下限の詳細は、gh-pages を再作成する必要がある場合や、サポート対象バージョンの範囲を変更する場合の参考資料です。

明示的なディスパッチを使う理由（タグプッシュトリガーではなく）。 docs-deploy.yml には tags: [v*] が記述されていますが、リリースタグは publish ジョブが GITHUB_TOKEN を使って gh release create で作成します。GITHUB_TOKEN で作成されたタグプッシュからは新しいワークフロー実行が開始されないため（ドキュメント）、この方法でリリースを切った場合、tags: [v*] トリガーは発火しません。そのため deploy-docs ジョブは、タグを入力として workflow_dispatch（GITHUB_TOKEN 下でも実行されるとドキュメントに記載された例外）経由で docs-deploy.yml を呼び出します。個人トークンを使って手動でタグを切った場合は、tags: [v*] プッシュトリガーが発火し、リリースワークフローのディスパッチは同じデプロイの no-op な再実行となりますが、どちらのパスも /vX.Y.Z/ に収束します。

自動的に行われること

  • deploy-docs ジョブは、/vX.Y.Z/ に配置されるビルドを起動します。
  • 「Stable」はポインターであり、コピーではありません。そのバージョンの docs ディレクトリをビルドして公開するのは、リリースタグのデプロイ（例: v0.8.0）です。bump-version.sh はリリースされたバージョンを docs/book/stable-version.txt に書き込みます。この変更を master に取り込むと、stable のメタデータのみが更新されます。master のデプロイはリリースタグの docs を再ビルドまたは再公開しません。stable-version.txt を gh-pages のルートにコピーし、ルートの / リダイレクトと、バージョンセレクターの「Stable (latest release)」エントリを再生成し、両方がそのリリースの公開済みバージョンディレクトリに解決されるようにします。指定されたバージョンディレクトリが gh-pages に存在しない場合、デプロイは明示的に失敗します。重複する /stable/ ツリーは存在しません。
  • 順序が重要です: タグのデプロイは、master デプロイが安定版ポインターをそこへ切り替える 前に、gh-pages 上に /vX.Y.Z/ を配置する必要があります。通常のリリース手順では、バージョン更新 PR が先にマージされるため（ステップ 2）、その master のドキュメントデプロイは通常、Release Stable がタグを作成してデプロイする 前に 実行されます。その先行する master デプロイでは /vX.Y.Z/ が存在しないことが検出され、意図的に以前のポインターが維持されます。切り替えは延期されます（docs-deploy.yml の遅延切り替えロジックを参照してください）。続いて deploy-docs ジョブが /vX.Y.Z/ を作成し、ディレクトリが利用可能になった後の 次の master デプロイで切り替えが公開されます。deploy-docs はタグビルドをディスパッチするだけで、その完了を待たない点に注意してください。成功した deploy-docs ジョブは、ディスパッチが受理されたことを意味するだけで、ドキュメントの実行が完了したことを意味しません。/vX.Y.Z/ が利用可能になったら、tag=master を指定して docs-deploy.yml をディスパッチし、安定版ポインターの切り替えを公開します（また、ディスパッチされた実行が Actions タブで実際に成功したことを確認してください）。
  • gh-pages は一時的なものです。デプロイのたびに単一のorphanコミットがforce-pushされ（履歴は蓄積されません）、DOCS_KEEP_VERSIONS によって保持期間が制御されます（masterに加えて最新のN個の最終リリースを保持し、プレリリースや古い最終リリースは削除されます）。これにより、クローンのサイズが一定に保たれます。
  • _shared/ ディレクトリ（UI CSS、JS、ファビコンを含む）はビルドから更新されるため、テーマはデプロイされたすべてのバージョンに反映されます。
  • 翻訳済みロケール（es、fr、ja、zh-CN）は docs/book/po サブモジュールからレンダリングされます。デプロイ時にはこのサブモジュールが submodules: recursive によって、デプロイされた ref がピン留めしているコミットで解決されます。そのピンはバージョン更新時に設定されます。更新、タグ付け、ピン留めの手順については Step 2 を参照してください。英語ではサブモジュールは不要です。

gh-pages のブートストラップ

gh-pagesが削除された場合、または完全に再作成する必要がある場合は、以下の特定の順序でバージョンをシードしてください。

  1. サポートされている最も古いリリース: タグ v0.7.5 を指定した workflow_dispatch
  2. 次回のリリース: タグ v0.8.0-beta-1 などを指定した workflow_dispatch。
  3. 現在の master: master タグを使用した workflow_dispatch

[!IMPORTANT] ブートストラップ時には master を最後にデプロイする必要があります。これは、他のすべてのバージョンが使用する確定的な _shared/ クロームレイヤーを書き込みます。

[!NOTE] Stable は docs/book/stable-version.txt（ソースにコミットされ、stable-version.txt として gh-pages ルートに公開される）から解決されます。ブートストラップ後、そのファイルが意図した GA リリースを指していることを確認してください。ルートリダイレクトと「Stable (latest release)」セレクターエントリはこれに従います。/stable/ ディレクトリは作成されません。

手動再デプロイとバージョンフロア

特定のバージョンを手動で再デプロイするには:

  1. Actions → Deploy mdBook docs to Pages に移動します
  2. Run workflow をクリックします
  3. タグを入力してください（例: v0.7.5 または master）

DOCS_MIN_VERSION の下限: 古すぎるバージョンやサポートされていないバージョンを誤ってデプロイしないように、ワークフローは最小バージョンの下限（現在は v0.7.5）を強制します。

  • DOCS_MIN_VERSION（v0.7.4 など）より古いタグは、ワークフローによって拒否されます。
  • cargo mdbook gen-versions（xtask ヘルパー）は、この下限より下の gh-pages 上のディレクトリをすべて無視し、バージョンのドロップダウンから除外します。

サポートを終了して古いバージョンを切り捨てるために下限を引き上げる必要がある場合：

  1. .github/workflows/docs-deploy.yml の DOCS_MIN_VERSION 環境変数を更新します。
  2. 古いバージョンのディレクトリは、次回のデプロイ時に DOCS_KEEP_VERSIONS の保持ポリシーによって自動的に削除されます。容量を回収するために gh-pages を手動で編集する必要はありません。

問題が発生した場合

実行が startup_failure で即座に終了する（作成されたジョブは 0 件）: これは許可リストの診断結果ではなく、症状として扱ってください。実行の概要とリポジトリの Actions ポリシーを確認します。GitHub が selected-actions rejection を報告し、リリースワークフローで最近 uses: refs が追加または変更された場合は、それらの refs を 許可されたアクション と比較してください。Settings → Actions → General で拒否されたパターンのみを追加し、設定が反映されるまで数分待ってから、新しい実行をディスパッチします。GitHub がポリシーによる拒否を報告していない場合は、代わりにワークフロー定義または他のリポジトリポリシーを調査してください。

validate failed: version mismatch: バージョン更新のPRがマージされていないか、誤ったバージョンを入力しています。不一致を修正して再実行してください。

環境ゲートがタイムアウトしました: タイムアウトしたジョブのみを再実行してください。ワークフローを再起動する必要はありません。

Scoop または AUR の配布ジョブが失敗した場合: それぞれに手動でトリガー可能なサブワークフローがあります。修正を確認するため、まず該当するものを dry_run: true で再実行し、その後 dry_run: false で再実行してください。これらはあると望ましいものです。配布ジョブが失敗しても、リリース自体が無効になることはありません。Scoop の認証情報関連の失敗の場合は、汎用的な dry run を認証情報の有効性の証明として扱うのではなく、Scoop Bucket Canary を使用してください。canary によって、fail-closed の credential_canary パスが有効になります。

crates.io パブリッシャーは、いくつかのクレートをアップロードした後で停止しました: バージョンを上げたり、2回目のリリースを開始したりしないでください。crates.io のバージョンは置き換えたり削除したりできません。同じリリースコミットで失敗したクレートを修正し、同じタグに対して dry_run: false を指定して Pub crates.io を再実行してください。パブリッシャーは最初にすべての <crate>@<version> を照会し、すでに公開されたバージョンをスキップします。最後に成功したクレートについては Publish ステップを確認してください。preflight が失敗した場合、アップロードは試行されておらず、問題はまだ元に戻せます。

scoop ジョブが remote: Permission ... denied to <account>（403）で失敗した場合: マニフェストの問題ではなく、権限の問題です。バケットトークンが無効になっているか、権限の範囲が不足しています。SCOOP_BUCKET_TOKEN のローテーション に従ってトークンをローテーションし、バケットに書き込まずに修正を確認するため、Scoop Bucket Canary をディスパッチします。dry_run: false で Scoop パブリッシャーを再実行し、バケットに新しいバージョンが反映されたことを確認します。バケット側の Excavator の復旧は、zeroclaw-labs/scoop-zeroclaw#1、リポジトリのワークフロー書き込み権限、およびメンテナーによるスモークテストが保留中のままです。これらの手順が完了するまで、リリースを修復するのを待たないでください。

週次の Scoop Bucket Canary が赤になった: トークンの有効期限が切れているか、書き込み権限を失っています。同じローテーション手順です。次のリリースまでに修正してください。

Homebrew Core が古くなっています: Homebrew はリリースワークフローのジョブではありません。リポジトリのフォークトークンを追加する代わりに、Homebrew autobump のステータスとドキュメント化された手動 bump パスを確認してください。

AUR ジョブが The AUR is down due to maintenance で失敗しました: 上流側の障害であり、認証情報の問題ではありません。ログの SSH key diagnostics に鍵のフィンガープリントが表示され、失敗が SSH ではなくサーバーに起因している場合、AUR_SSH_KEY は問題ありません。パブリッシャーはジョブに強制タイムアウトを設定し、約 7 分間に 5 回再試行します。各試行では現在のパッケージを再クローンし、別の実行ですでに新しいバージョンが公開されている場合は、ダウングレードせずに停止します。メンテナンスエラーに到達したということは、その時間がリトライ予算を超えたことを意味します。aur.archlinux.org が復旧するまで待ち、その後、リリースタグで Pub AUR Package を dry_run: true にして再ディスパッチし、続いて dry_run: false にします。curl -fsS 'https://aur.archlinux.org/rpc/v5/info?arg%5B%5D=zeroclawlabs' で結果を確認するか、単に AUR Freshness Check をディスパッチします。これをスキップすると、週次チェックが検出するまで AUR は気付かれないまま遅れた状態になります。

AUR が意図的にロールバックされた安定版リリースより新しい場合: ロールバックタグとパッケージの内容を確認してください。公開済みパッケージに、ロールバックタグには含まれていないゼロ以外の epoch がある場合は、古いタグを再ディスパッチしないでください。リリースメタデータは不変のタグから取得されるため、デフォルトブランチの編集ではその実行を変更できません。その代わり、差し戻したコードを含む、バージョン番号を進めた安定版リリースを準備し、dist/aur/PKGBUILD に対応する epoch= の設定を追加し、cargo generate installers を実行して dist/aur/.SRCINFO を再生成し、両方のファイルを確認してから、マージし、新しいリリースタグを作成してください。そのタグが公開されるまで、鮮度チェックは赤のままです。エポック境界をまたぐために allow_downgrade を決して使用しないでください。同じエポック内のロールバックの場合は、まず dry_run: true を指定して手動の Pub AUR Package ワークフローを一度実行し、メタデータ生成とバージョンガードの対象側を検証してから、dry_run: false と allow_downgrade: true を指定して実行してください。ドライランでない場合のガードでは、新しく取得した AUR クローンも追加で比較します。このオーバーライドは手動ディスパッチでのみ利用できます。再利用可能なインターフェースではこの入力を宣言していないため、要求できません。形式不正な AUR メタデータや説明のないバージョン不一致を回避するために、これを決して使用しないでください。

同じバージョンでパッケージファイルが異なるため、公開が停止されました: パブリッシャーは、既存の epoch:pkgver-pkgrel タプルに対して異なるファイルを意図的に置き換えることを拒否します。差分を確認してください。権限を持つ AUR メンテナーは、そのリリースタグから生成された正規の PKGBUILD と .SRCINFO を復元するか、修正済みのソース変更をマージして新しい安定版リリースタグで公開する必要があります。デフォルトブランチを編集して古いタグを再ディスパッチしても機能しません。パブリッシャーは不変のタグからメタデータを読み取るためです。

公開時に、数値ではない、またはその他の形式不正な現在の AUR バージョンが報告される: 自動公開処理は意図的にフェイルクローズし、allow_downgrade では形式不正なメタデータを回避できません。承認された AUR メンテナーが、手動で AUR にプッシュしてパッケージを正しい形式の epoch:pkgver-pkgrel に修正し、AUR RPC を通じて検証してから、通常の公開処理を再ディスパッチする必要があります。形式不正な公開状態を比較可能にするためにガードを弱めないでください。

レガシーワークフローを削除しました

以前 .github/workflows/ に存在していたいくつかの自動公開ワークフローは、レビューを回避したり取り消し不能な公開を行ったりするため削除されました。これらはもう存在しません。もし PR でいずれかが再び現れた場合は、リグレッションとして扱いブロックしてください。

ワークフロー削除された理由
release-beta-on-push.ymlmaster へのプッシュごとに自動的に公開されます
publish-crates-auto.ymlバージョン変更時にcrates.ioへ自動公開、取り消し不可
version-sync.ymlボットとしてレビューを回避し、master に直接コミットしました
checks-on-pr.yml重複した CI: 紛らわしい矛盾したステータスが発生しました
pre-release-validate.yml未使用の生成チェックリスト。このランブックが置き換えます

残っているワークフロー（自動および手動）の完全な一覧は CI & Actions を参照してください。

今後の展望

このランブックと release-stable-manual.yml は、最終目的地ではなく橋渡しの役割を担うものです。

目標とする最終状態:

  • release-plz はバージョンの更新と変更履歴を自動的に管理します
  • 単一の release.yml が、現在のサブワークフローの寄せ集めを置き換えます
  • SLSA provenanceはパイプラインに組み込まれています
  • チームはリリースを行う際、ランブックに従うのではなく、リリースPRをマージすることで行います

それが実現するまでは、このプロセスを使用してください。このランブックを使って手動でリリースを切るたびに、それが自動化に必要な処理を明らかにする練習になります。