リリース復旧ランブック
追加型リリースモデルのもとで、途中で失敗したリリースを、公開済みの履歴を書き換えずにステージごとに復旧する手順。
このランブックは、ahmed-g-gad/apothem の vX.Y.Z リリースが途中で失敗したときに、動作する状態を復元します。
リリースサイクルランブックと同じリリースモデル、すなわち追加型モデルに従います。
各リリースは main に 1 つのコミットと、署名付きの注釈付きタグを 1 つ追加します。タグのプッシュによって、リリースワークフローと npm ワークフローが実行されます。
何も強制プッシュされることはなく、main の履歴が書き換えられることは決してありません。
公開済みの履歴は恒久的です。
プロジェクトが公開したすべてのリリースタグ、GitHub Release、npm バージョンは公開されたままです。
npm のバージョンは不変です。公開済みの name@version は決して置き換えられず、公開が取り消されたバージョン番号は二度と使用できません。
したがって、復旧は新しいパッチリリースによって前に進みます。ユーザーがすでにインストールしている可能性のあるものを削除したり、付け替えたりはしません。
1. ステージの分類
| ステージ | アクション | 失敗モード | 復旧パス |
|---|---|---|---|
| 1 | リリースコミットを main に着地させる（リリースサイクルランブックの §2.1） | リリースコミットで CI が失敗する | main への別のコミットで前方修正する。CI がグリーンになるまでタグを付けない |
| 2 | 署名付きの注釈付きタグをプッシュする | プッシュが拒否される、またはタグが署名されていないか誤ったコミット上にある | 下記の §2 |
| 3 | release.yml が GitHub Release をビルド、署名、公開する | ジョブが失敗する、またはアセットが欠落している | 下記の §3 |
| 4 | publish-npm.yml が @ahmed-g-gad/apothem を公開する（同じタグのプッシュで実行される） | 公開が失敗する | 下記の §3 |
| 5 | Pages とリポジトリのメタデータ | サイトまたはメタデータが古い | 下記の §3 |
すべての復旧アクションは冪等です。 クリーンな状態で実行しても何も起こりません。部分的な状態で実行すると、期待されるステージ後の状態が復元されます。
2. タグの復旧
タグを診断します。
git fetch origin --tags
git ls-remote origin refs/tags/vX.Y.Z
git cat-file -t vX.Y.Z # "tag" for an annotated tag
git tag -v vX.Y.Z # signature check何をすべきかは、そのタグから何かが公開されたかどうかによって決まります。
-
まだ何も公開されていない場合（リリースワークフローが publish ジョブより前に失敗し、かつ
publish-npm.ymlが公開しなかった）: タグを削除し、同じコミットに-a -sで再度タグを付けます。git push --delete origin vX.Y.Z git tag -d vX.Y.Z git tag -a -s vX.Y.Z -m "vX.Y.Z" <release-commit-sha> git push origin vX.Y.Z -
何かが公開された場合（アセット付きの GitHub Release、または npm バージョン）: タグを移動、削除、再利用することは決してしないでください。
vX.Y.(Z+1)で前方修正します。
タグ名が別のコミットに再利用されることは決してありません。
3. パブリッシャーの復旧
各パブリッシャーは個別に再試行します。
| 面 | 診断 | 復旧 |
|---|---|---|
| リリースワークフロー | gh run view <run-id> --log が失敗したジョブを示す | gh run rerun <run-id> --failed。Check the plugin version changed with the plugin での失敗は、バージョンが引き上げられていなかったことを意味する。リリースサイクルランブックの障害表を参照 |
| GitHub Release | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | publish GitHub Release ジョブを再実行する。このジョブは既存のリリースを編集し、--clobber でアセットを再アップロードする |
| npm | npm view @ahmed-g-gad/apothem version と npx @ahmed-g-gad/[email protected] --version | パッケージの npm Trusted Publishing を確認したうえで、vX.Y.Z に対して publish-npm.yml を再実行する（gh workflow run publish-npm.yml --field tag=vX.Y.Z）。npm のバージョンは不変であるため、バージョンがすでにレジストリにある場合、ワークフローは公開をスキップする |
| Pages | gh run list --workflow=publish-static-site.yml --limit=1 と curl -sSI https://apothem.ahmedgad.com/ | publish-static-site.yml を再実行する。CNAME が引き続き ahmed-g-gad.github.io に解決されることを検証する |
| リポジトリのメタデータ | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | 説明、ホームページ、トピックをその場でパッチする。リポジトリを決して再作成しない |
4. ロールバック
不良リリースは、それを削除することによってではなく、その修正をリリースすることによってロールバックします。
-
問題のあるコミットを
main上でリバートします（通常のリバートコミット）。 -
リリースサイクルランブックに従って
vX.Y.(Z+1)をカットします。 -
不良バージョンに印を付けます。その
CHANGELOG.mdセクションに### Yankedの注記を追加し、その GitHub Release のノートを修正版を指すように編集し、npm 上で非推奨にします。npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
不良なタグ、GitHub Release、npm バージョンは公開されたままなので、ピン留めされたインストールと再現可能なビルドは引き続き解決されます。 ロールバックはリリースインシデントとして記録してください。
5. リリースファサードルール
リポジトリのリリースファサードルール（コントリビューター向け指示の Release Facade セクション）は、上記の追加型モデルを述べています。 公開済みのタグ、GitHub Release、npm バージョンは、いずれも公開されたままです。 「現在のバージョンのみ」という要件が対象とするのは、公開面が示す内容です。 このランブックは、公開済みのタグ、GitHub Release、npm バージョンを削除したり書き換えたりすることは決してありません。
6. 相互参照
- リリース手順: リリースサイクルランブック。
- リリースポリシー: リリースエンジニアリングポリシー。
- タグオブジェクトとそれぞれの検証方法: SECURITY.md のリリース署名セクション。
- Pages の構成:
site/content/docs/runbooks/pages-enablement.mdx。