이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

릴리스 롤백 런북

상태: 활성 범위: 공개, 현재 상태 최종 검토: 2026-09-03 담당: AX Code 릴리스 엔지니어링

이 런북은 게시된 안정(latest 채널) AX Code CLI 릴리스를 철회하고 이전 릴리스를 되돌리는 방법을 설명합니다. 사전 릴리스(beta 채널)는 Homebrew tap이나 winget을 건드리지 않으므로, 되돌리려면 아래 GitHub 릴리스 단계만 하면 됩니다.

기능 버그에는 앞쪽 핫픽스(vX.Y.Z+1를 내보내는 것)를 우선합니다. 롤백은 릴리스 무결성 실패에만 사용합니다. 깨졌거나 잘못 서명된 아티팩트, 손상된 설치 프로그램, 채널/태그 실수(예를 들어 사전 릴리스 태그를 latest에 게시한 경우), 빠른 수정이 없는 심각한 회귀입니다.

1. 채널을 멈춥니다

롤백이 끝날 때까지 추가 릴리스와 postpublish_only 재개를 멈춥니다. 릴리스 워크플로는 이미 게시된 릴리스의 자산을 바꾸지 않으므로, 동시에 다시 실행해도 되돌리는 중인 상태를 덮어쓸 수 없습니다.

2. GitHub 릴리스를 다시 가리킵니다

문제가 된 릴리스를 사전 릴리스로 표시하면 latest가 이전 태그를 가리키게 됩니다. 릴리스 노트가 덮어씌워졌으면 이전 노트를 복원합니다.

gh release edit "vX.Y.Z" --repo defai-digital/ax-code --prerelease
gh release edit "vX.Y.(Z-1)" --repo defai-digital/ax-code --latest

문제가 된 릴리스의 자산이 손상되었거나 잘못 서명되었다면, 설치 프로그램이 가져가지 못하도록 함께 삭제합니다.

gh release delete-asset "vX.Y.Z" "<asset-name>" --repo defai-digital/ax-code

아티팩트를 조사하기 전에는 릴리스 객체 자체를 삭제하지 마십시오. 서명된 자산과 워크플로 로그가 사후 분석의 증거입니다.

3. Homebrew tap을 되돌립니다

bash .github/scripts/update-homebrew.sh가 공유 defai-digital/homebrew-tap 저장소에 formula 커밋을 푸시했습니다. 그 커밋을 되돌리면 brew upgrade ax-code가 다시 이전 버전을 제공합니다. 이전 defai-digital/homebrew-ax-code 저장소에는 마이그레이션 메타데이터만 있습니다. 그 formula를 복원하지 마십시오.

git -C homebrew-tap revert --no-edit <formula-commit>

이후 복원된 버전에 대해 Homebrew 스모크 작업(.github/workflows/install-matrix-smoke.yml)으로 수렴을 확인합니다.

4. winget 매니페스트를 되돌립니다

winget 매니페스트는 GitHub 릴리스에 첨부된 매니페스트 ZIP에서 microsoft/winget-pkgs로 유지관리자가 제출합니다. 문제가 된 버전이 이미 승인되었다면 그 매니페스트 파일을 되돌리는 PR을 엽니다. 아직 검토 중이면 PR을 닫습니다. 릴리스의 --clobber 업로드는 첨부 ZIP만 바꾸며, 게시된 패키지는 바꾸지 않습니다.

5. 알립니다

릴리스 토론과 지원 채널에 짧은 메모를 올립니다. 영향받은 버전, 복원된 버전, 다시 설치하는 방법을 적습니다.

• Homebrew: brew update && brew upgrade ax-code(또는 brew uninstall ax-code && brew install ax-code).
• Windows와 그 외: 이전 릴리스 페이지의 고정된 설치 프로그램을 다시 실행합니다. 설치 프로그램은 서명이 맞지 않으면 진행하지 않고 멈추며, SHA-256을 확인한 고정 minisign를 부트스트랩합니다.

6. 복원된 상태를 확인합니다

1. GitHub latest 릴리스가 이전 태그를 가리키고 모든 자산이 검증되는지 확인합니다.

   gh release download "vX.Y.(Z-1)" --repo defai-digital/ax-code -p '*.zip' -p '*.minisig'
   minisign -V -p docs/release/ax-minisign.pub -m ax-code-darwin-arm64.zip -x ax-code-darwin-arm64.zip.minisig

2. Homebrew formula가 복원된 버전을 제공하고, 깨끗한 러너에서 깨끗하게 설치되는지 확인합니다. 설치 매트릭스 스모크 워크플로가 이 일을 합니다.

3. 새로 설치한 환경에서 ax-code --version이 복원된 버전을 보고하고 ax-code doctor을 통과하는지 확인합니다.

7. 사후 분석

릴리스 관문을 통과하고도 깨진 채로 나간 원인을 기록하고, 다음 릴리스 전에 .github/workflows/release.yml(검증, 스모크 범위)에 대한 수정을 제출합니다. 어느 단계든 적힌 대로 동작하지 않았다면 이 런북을 갱신합니다.