Runbook pemulihan rilis

Prosedur pemulihan untuk memulihkan repositori ketika urutan rilis gagal di tengah jalan, dengan diagnostik tahap demi tahap.

Runbook ini memulihkan ahmed-g-gad/apothem ke keadaan yang berfungsi ketika urutan rilis bersih-total-di-tempat gagal di tengah jalan. Repositori publik tidak dihapus atau dibuat ulang selama rilis. Pemulihan bergantung pada tag keamanan riwayat khusus-rilis, klon lokal pengelola, dan keadaan manajer paket hilir.

1. Taksonomi tahap

Tahap	Tindakan	Mode kegagalan	Jalur pemulihan
1	Tangkap dan dorong tag keamanan riwayat	Tag hilang, tidak ditandatangani, atau menunjuk ke grafik yang salah	Buat ulang tag dari titik merge pra-squash sebelum memindahkan `main`
2	Verifikasi CI, benteng audit, keadaan paket, dan changelog	Gerbang mana pun gagal	Hentikan; perbaiki secara lokal; jangan pindahkan `main`
3	Pindahkan `main` ke satu commit rilis yang ditandatangani	force-with-lease gagal, commit tidak ditandatangani, atau pesan commit salah	Reset `main` lokal ke commit yang ditandatangani yang dimaksudkan dan coba lagi dengan lease baru
4	Publikasikan GitHub Release, Pages, npm, dan metadata	Sebuah penerbit atau permukaan verifikasi gagal	Pertahankan commit rilis; jalankan ulang hanya penerbit yang gagal setelah mencatat kegagalan

Setiap tindakan pemulihan bersifat idempoten. Menjalankannya pada keadaan bersih adalah no-op; menjalankannya pada keadaan parsial memulihkan kondisi pasca-tahap yang diharapkan.

2. Pemulihan tag keamanan

Verifikasi tag keamanan sebelum penulisan ulang riwayat apa pun:

git fetch origin --tags
git show --summary --show-signature <history-safety-tag>
git merge-base --is-ancestor origin/main <history-safety-tag>

Diharapkan: tag ada, verifikasi tanda tangan berhasil ketika tag ditandatangani, dan grafik pra-squash lengkap dapat dijangkau dari tag. Jika tag hilang secara lokal tetapi ada di remote, ambil. Jika hilang di remote, hentikan rilis dan buat ulang sebelum menyentuh main:

git tag -s <history-safety-tag> <pre-squash-commit>
git push origin <history-safety-tag>

3. Pemulihan branch utama

Diagnosis keadaan main publik:

gh api repos/ahmed-g-gad/apothem/commits/main \
  --jq '.sha, .commit.message, .commit.verification.verified, .commit.verification.reason'

Diharapkan setelah peralihan: pesannya tepat release: Apothem <release-version> dan verification.verified adalah true.

Jika push force-with-lease gagal sebelum mengubah GitHub, biarkan remote apa adanya, ambil, bangun ulang commit rilis yang ditandatangani secara lokal, dan coba lagi hanya setelah lease cocok:

git fetch origin main
git push --force-with-lease=main:<expected-remote-sha> origin main

Jika push mendarat dengan commit yang tidak ditandatangani atau tidak diverifikasi, perbaiki konfigurasi penandatanganan lokal, buat ulang commit rilis dari pohon yang sama, dan lakukan force-push lagi dengan lease. Jangan hapus tag keamanan.

4. Pemulihan penerbit

Setiap penerbit dicoba ulang secara independen setelah commit rilis GitHub diverifikasi:

Permukaan	Diagnostik	Pemulihan
GitHub Release	`gh release view <release-tag> --json tagName,isDraft,isPrerelease,assets`	Hapus hanya draf yang cacat; jika tidak, unggah aset yang hilang dengan `gh release upload --clobber`
Tag rilis	`git ls-remote origin refs/tags/<release-tag>` dan `git tag -v <release-tag>`	Tag ulang dari SHA yang sama dengan `-a -s` jika tag hilang atau tidak ditandatangani; jangan pernah gunakan ulang nama tag untuk commit yang berbeda
npm	`npm view @ahmed-g-gad/apothem version` dan `npx @ahmed-g-gad/apothem@<version> --version`	Jalankan ulang `publish-npm.yml` untuk `<release-tag>` setelah mengonfirmasi npm Trusted Publishing untuk `@ahmed-g-gad/apothem`
Pages	`gh run list --workflow=publish-static-site.yml --limit=1` dan `curl -sSI https://apothem.ahmedgad.com/`	Jalankan ulang `publish-static-site.yml`; verifikasi bahwa CNAME masih ter-resolve ke `ahmed-g-gad.github.io`
Metadata GitHub	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	Tambal deskripsi, beranda, dan topik di tempat; jangan buat ulang repositori

5. Rollback

Rollback adalah pilihan terakhir. Utamakan pemulihan penerbit yang tertarget terlebih dahulu. Jika satu commit rilis harus dibatalkan, pulihkan main dari tag keamanan:

git fetch origin --tags
git switch main
git reset --hard <history-safety-tag>
git push --force-with-lease origin main

Setelah rollback, jalankan ulang CI, terapkan ulang proteksi branch jika GitHub melaporkan penyimpangan, dan catat rollback sebagai insiden yang memblokir rilis. Pertahankan tag rilis hanya jika artefak rilis tetap valid; jika tidak, hapus rilis dan tag yang cacat sebelum mencoba lagi.

6. Referensi silang

Konfigurasi Pages: site/content/docs/runbooks/pages-enablement.mdx.
Prosedur rilis: site/content/docs/runbooks/release-cycle.mdx.
Resep pengemasan: packaging/README.md.
Jangkar pemulihan: tag keamanan riwayat khusus-rilis.