ship-workflow-land

Land — merge PR and verify deployment

Entry/Exit

• Entry: PR that has passed review
• Exit: docs/features/<name>/07-deploy-report.md
• Output path: 07-deploy-report.md → ship-workflow-canary
• Points to: deployment success suggestion ship-workflow-canary monitoring
• Preload: CANON.md

When not to use

• The PR has not yet passed review or still has blocking issues
• The current task is only a local commit, version bump, or preparing the ship checklist
• The merge is already complete and only canary or doc sync is needed

Iron Law

Process

Step 1: Detect PR

Confirm PR status:gh pr view --json number,title,reviewDecision,statusCheckRollup,mergeable

Preconditions: OPEN + APPROVED + MERGEABLE. If not met, stop and report the blockers.

Step 2: Wait for CI to pass (Green CI Gate)

Continuously monitor CI until all green or timeout (15 minutes).

Timeout handling: 15-minute timeout → report which checks are still running; CI failure → stop, do not merge. View failure logs:gh run view <run-id> --log-failed

Only allowed action when CI fails: Fix on the PR branch → push → wait for CI to be all green again. Never merge while CI is red.

Step 3: Merge readiness check

Final confirmation after CI is green:

• CI is all green (not "mostly green")
• Review has not expired (approved within 7 days; re-confirm if expired)
• PR body accurately describes the changes
• If the PR branch is behind base, rebase or merge base first

Step 4: Merge PR

gh pr merge --squash --delete-branch  # 默认策略
gh pr merge --merge --delete-branch    # 项目约定用 merge commit 时

Verify after merge: confirm state=MERGED. Delete the remote branch immediately; clean up the local branch after deployment succeeds.

Step 5: Detect deployment strategy

Read project configuration to determine the deployment method:

Detected	Deployment method	Verification method
.github/workflows/deploy.yml	GitHub Actions	gh run list --workflow=deploy.yml
vercel.json / netlify.toml	Platform auto-deploy	curl Deployment URL
fly.toml	Fly.io	fly status
Dockerfile + K8s config	Container orchestration	kubectl rollout status
No auto-deploy config	Manual deployment	Ask human partner

Step 6: Wait for deployment to complete (Readiness Probe)

Monitor progress according to the deployment strategy. 10-minute timeout. After timeout, do not assume failure—report the status and let the human partner decide.

Step 7: Health verification

curl the health check endpoint (/health、/api/status、/api/readyz、/version）。

Pass conditions: all endpoints return the expected status + response time < 5000ms + /version returns the new version number. Do not auto-rollback on failure; report the results and let the human partner decide.

Step 8: Rollback capability confirmation

Get the merge commit SHA and verify the revert command is available. Rollback playbook:git revert -m 1 <sha> → git push origin main → wait for auto-deploy.

Rollback triggers: health check 5xx, critical business process unavailable, human partner request.

Output

Generate docs/features/<name>/07-deploy-report.md, as the production deployment closure record, including deployment scope, ship/canary carry-over status, CI / merge status, deployment strategy, production verification evidence, rollback readiness, final deployment status, and follow-up owner.

Verification evidence

Output or records must include: input/source, executed actions, verification results, blockers/fallbacks.

Common excuses

Excuse	Reality	Consequence
"CI is red but it's just a flaky test"	A flaky test is also a problem. Fix it or remove it; you cannot ignore a red light.	The team's CI trust drops to zero within 2 weeks, and real failures are masked >60% of the time.
"Merge first and deal with it later, CI is running"	Merging while CI is red = pushing forward even though you know there is a problem.	Fix cost escalates from 30min within the PR to 2-4h for a main branch hotfix.
"No need to wait for deployment, we have monitoring anyway"	Not waiting for deployment verification = pushing verification onto users.	Failures are exposed on the user side and take 15-30min, affecting 500+ users.
"Squash merge will lose history"	Squash keeps the main branch readable. Detailed history is fully preserved in the PR.	Without squash: after 3 months the main branch history swells 10x, and bisect efficiency drops 80%.
"Small PRs don't need health verification"	A one-character configuration error can also make the service return 500. PR size and impact size are unrelated.	A single-character typo causes a service outage, and failure discovery is delayed 30min.

Red flags

• Attempting to merge while CI is red
• Skipping health verification and directly declaring "deployment successful"
• Not deleting the remote branch after merging (branch leakage)
• Merging a review from 7 days ago without reconfirming
• Starting to "wait for deployment" without confirming the deployment strategy
• Assuming success after a deployment timeout
• Merging without a rollback path
• No one watching during the first hour after merging

Verification failure handling

Failure scenario	Handling method
CI failure	Block the merge, fix on the PR branch and push again, wait for all green
Review expired (>7 days)	Block the merge, ask the human partner to reconfirm
Merge conflict	Resolve by rebasing/merging the PR branch onto the base, push again, and wait for CI
Deployment timeout	Do not assume failure; report status and let the human partner decide
Health check 5xx or timeout	Do not automatically roll back; report the result and recommend operating according to the rollback plan

Verification checklist

• PR review status is APPROVED
• CI is all green (no exceptions)
• Review is not expired (within 7 days)
• PR body accurately describes the changes
• PR has been successfully merged (state=MERGED)
• Remote branch has been cleaned up
• Deployment strategy has been detected
• Deployment has completed successfully
• All health check endpoints pass
• The new version number has been confirmed
• The rollback path has been verified
• Ship / Canary Carryover has been brought into 05-ship.md and 06-canary-report.md status
• Production Verification has recorded health, version, critical paths, and monitoring evidence
• Final Deployment Status has recorded deployed / rolled-back / paused / failed
• Follow-up / Ownership has recorded the remaining actions and next command
• 07-deploy-report.md generated

Output template

Template start:templates/feature/07-deploy-report.md

# <Feature Name> — Deploy Report

## Deploy Summary
- Owner:
- Date:
- PR:
- Merge SHA:
- Status: pending / merged / deployed / rolled-back / blocked

## Deploy Scope
- Environment:
- Service / app / artifact:
- Version / commit / release:
- Target users / traffic:
- Explicitly out of scope:

## Ship / Canary Carryover
- Ship decision:
- Ship source:
- Canary result:
- Canary source:
- Conditions carried into deploy:

## CI / Merge Status
- Review status:
- CI result:
- Duration:
- Expired approvals:
- Merge method:
- Branch cleanup:

## Deployment Strategy
- Strategy:
- Deployment target:
- Version confirmed:
- Rollout mode:
- Deployment evidence:

## Production Verification
| Check | Source | Expected | Actual | Result |
|-------|--------|----------|--------|--------|

## Rollback Readiness
- Command:
- Trigger conditions:
- Estimated time:
- Data / migration handling:
- Owner:

## Final Deployment Status
- Final status: deployed / rolled-back / paused / failed
- Decision reason:
- Production URL / artifact path:
- Completed at:

## Follow-up / Ownership
- Canary requirement:
- Monitoring owner:
- Remaining actions:
- Tracking:
- Next command: `/canary` / `/retro` / `/doc-sync` / none