Release flow — `axe ship`

AI 요청 프롬프트


https://docs.axelabs.ai/ops/runbook/release-flow 따라 본 repo 변경 release 해줘.

진행:
1. 현재 repo + branch + 변경 상태 진단 (git status + git log origin/main..HEAD + 동반 docs 갱신 commit 존재 여부)
2. 페이지 "Service 매핑" 표 확인 — 본 repo 의 deploy hook 자동/수동 분기
3. 페이지의 각 Step (docs-check → branch clean → push preview → confirm → push → deploy hook) 매 step 결과 받고 다음. 특히 Step 4 confirm 직전 사용자 확인
4. 함정 발생 시 페이지 "함정" 표 따라 우회 (docs commit 누락 / cross-repo drift / feature branch)
5. 배포 완료 후 production 검증 + (선택) updates.mdx Ship Log 한 줄 추가

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

Problem: 코드 변경 후 docs (axelabs-docs/content/*.mdx) 갱신을 깜빡하면 production 사이트가 거짓말을 함. 매 commit 마다 hook 으로 강제하면 WIP commit 이 막혀서 --no-verify 우회 습관이 생김 → hook 사실상 무력화.

Solution: release 시점에만 강제. git push origin main 의 자리에 axe ship 를 둬서, production 으로 나가는 모든 push 가 docs-drift 검증을 통과해야 함. WIP / feature branch push 는 raw git 으로 그대로 사용.

한 줄 요약


# 이전 습관
git push origin main && ssh axe-macmini "cd /Users/axe/<service> && docker compose ..."
 
# 새 습관
axe ship          # 현재 repo 자동 감지 → docs-check → push → deploy
axe ship frame    # 명시
axe ship docs     # docs SSOT 자체 배포

무엇을 하는가

Step	동작	실패 시
1	`axe docs-check --since origin/main` (현재 repo)	abort — 누락 mdx 페이지 출력 후 종료
2	branch == `main` && working tree clean	abort
3	`git log origin/main..HEAD` 출력 (push 될 commit 미리보기)	nothing-to-push → abort
3b	`axelabs-docs` 에 unpushed commit 있나? 있으면 경고	(계속 진행, 단순 hint)
4	`yes/no` confirm 프롬프트	abort
5	`git push origin main`	git push 자체 실패면 abort
6	service 별 deploy hook (아래 표)	(배포 실패는 알림, push 는 이미 완료)

Service 매핑

`axe ship SERVICE`	repo	deploy hook
`frame`	`/Users/axe/frame`	`cmd_deploy` (blue/green swap, plan §3 D-config-13)
`blueprint`	`/Users/axe/blueprint`	`cmd_blueprint_upgrade` (sequential blue/green)
`docs`	`/Users/axe/axelabs-docs`	`docker compose up -d --build` (단일 컨테이너, ~30-60s 다운)
`hive`	`/Users/axe/hive`	(자동화 X) manual hint 출력
`stream`	`/Users/axe/stream`	(자동화 X) manual hint 출력
`magnet`	`/Users/axe/magnet`	(자동화 X) manual hint 출력

hive/stream/magnet 의 blue/green CLI 가 axe deploy 에 들어오면 매핑 갱신.

옵션


axe ship [service]
  --dry-run     # 실행 안 함, 어떤 step 이 무엇을 할지만 출력
  --no-deploy   # docs-check + push 까지만, 배포 hook skip (배포는 나중에 수동)

escape hatch 없음. --skip-docs-check 같은 플래그는 의도적으로 만들지 않음. drift 가 있다면:

axelabs-docs/content/PAGE.mdx 수정
cd /Users/axe/axelabs-docs && git add -A && git commit -m 'docs: ...'
axe ship docs (production 반영)
원 repo 로 돌아와 axe ship SERVICE 재실행

docs SSOT 의 특수성

axe ship docs 는 docs-check 를 skip 함 (자기가 SSOT 인데 자기 자신과 drift 비교는 무의미). 대신:

branch + working tree clean 검사는 동일
push 후 docker compose up -d --build 로 즉시 production 반영
배포 시간 ~30-60s, 단일 컨테이너 (blue/green X)

운영 순서

코드 변경이 docs 영향이 있는 경우 (대부분):


# 1. 코드 작업 (frame 예시)
cd /Users/axe/frame
# ... 작업 ...
git add -A && git commit -m "feat(frame): add foo MCP tool"
 
# 2. docs 갱신
cd /Users/axe/axelabs-docs
vim content/services/frame.mdx   # MCP Tools 표에 foo 추가
git add -A && git commit -m "docs(frame): document foo MCP tool"
 
# 3. docs 먼저 배포 (frame ship 의 docs-check 가 통과되도록 origin/main 에 docs commit 도달)
cd /Users/axe/axelabs-docs
axe ship                          # docs 자동 감지, push + rebuild
 
# 4. frame 배포
cd /Users/axe/frame
axe ship                          # frame 자동 감지, docs-check 통과, push + blue/green swap

함정

함정	결과	회피
`axe ship` 대신 `git push origin main` 직접	docs-check 미실행 → drift 누적	release-worthy push 는 반드시 `axe ship`
feature branch 에서 `axe ship`	”current branch is X, expected main” abort	merge to main 먼저
docs commit 안 한 채 `axe ship frame`	docs-check fail, push 거부	docs 먼저 commit + ship
`axe ship docs` 전에 `axe ship frame`	docs commit 은 frame repo origin/main 에서 보임 → check 통과, but production 사이트는 옛 mdx	docs 먼저 ship (cross-repo 경고가 출력됨)
다른 사람의 mdx 변경이 origin/main 에 있음	docs-check 통과 (이미 mdx 있음)	정상 — 다른 push 가 이미 docs 채움

왜 pre-commit hook 이 아닌가

자세한 의사결정 근거: D-ops-N (release-gate-not-precommit). 요약:

pre-commit hook 은 WIP commit 마다 발화 → 노이즈 → --no-verify 습관화 → hook 사실상 죽음
release-gate (axe ship) 는 운영자가 의도해서 호출하는 단 한 곳에 검증을 집중 → 우회 유혹 적음
솔로 운영자 + Claude Code 주 개발자 환경에서 ROI 가 가장 높은 지점

Release flow — axe ship