# Ship Workflow Land

> 合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"

- Skill: `zeroz-lab/ship-workflow-land` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/ship-workflow-land`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/ship-workflow-land/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/ship-workflow-land

---


# Land — 合并 PR 并验证部署


## 入口/出口
- **入口**: 通过 review 的 PR
- **出口**: `docs/features/<name>/07-deploy-report.md`
- **输出路径**: `07-deploy-report.md` → `ship-workflow-canary`
- **指向**: 部署成功建议 `ship-workflow-canary` 监控
- **前置加载**: CANON.md

## 何时不使用
- PR 尚未通过 review 或仍有阻塞问题
- 当前任务只是本地提交、版本 bump 或准备 ship checklist
- 合并已经完成，只需要 canary 或 doc sync

## Iron Law

<HARD-GATE>
没有绿色 CI 就不合并。CI 红灯 = 不碰合并按钮。
CI 红灯时合并 = 把已知问题推给下一个发现它的人。
</HARD-GATE>

## 流程

### Step 1：检测 PR

确认 PR 状态：`gh pr view --json number,title,reviewDecision,statusCheckRollup,mergeable`

前置条件：OPEN + APPROVED + MERGEABLE。不满足时停止并报告阻塞项。

### Step 2：等 CI 通过（Green CI Gate）

持续监控 CI 直到全部绿色或超时（15 分钟）。

**超时处理：** 15 分钟超时 → 报告哪些 check 仍在运行；CI 失败 → 停止，不合并。查看失败日志：`gh run view <run-id> --log-failed`

**CI 失败时唯一允许操作：** 在 PR 分支修复 → 推送 → 重新等待 CI 全绿。绝不在 CI 红灯时合并。

### Step 3：合并准备度检查

CI 绿色后最终确认：
- [ ] CI 全部绿色（不是"大部分绿色"）
- [ ] Review 未过期（7 天内批准，超期需重新确认）
- [ ] PR body 准确描述了变更
- [ ] 如 PR 分支落后于 base，先 rebase 或 merge base

### Step 4：合并 PR

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

合并后验证：确认 `state=MERGED`。远程分支立即删除；本地分支在部署成功后再清理。

### Step 5：检测部署策略

读取项目配置确定部署方式：

| 检测到 | 部署方式 | 验证方法 |
|--------|---------|---------|
| `.github/workflows/deploy.yml` | GitHub Actions | `gh run list --workflow=deploy.yml` |
| `vercel.json` / `netlify.toml` | 平台自动部署 | `curl` 部署 URL |
| `fly.toml` | Fly.io | `fly status` |
| `Dockerfile` + K8s 配置 | 容器编排 | `kubectl rollout status` |
| 无自动部署配置 | 手动部署 | 询问 human partner |

### Step 6：等部署完成（Readiness Probe）

根据部署策略监控进度。10 分钟超时。超时后不假设失败——报告状态让 human partner 决定。

### Step 7：健康验证

curl 健康检查端点（`/health`、`/api/status`、`/api/readyz`、`/version`）。

通过条件：所有端点返回预期 status + 响应时间 < 5000ms + `/version` 返回新版本号。失败时不自动回滚，报告结果让 human partner 决定。

### Step 8：回滚能力确认

获取合并 commit SHA，验证 revert 命令可用。回滚剧本：`git revert -m 1 <sha>` → `git push origin main` → 等待自动部署。

回滚触发条件：健康检查 5xx、关键业务流程不可用、human partner 要求。

### 输出

生成 `docs/features/<name>/07-deploy-report.md`，作为 production deployment closure record，包含部署范围、ship/canary 带入状态、CI / merge 状态、部署策略、生产验证证据、回滚就绪、最终部署状态和 follow-up owner。

## 验证证据

输出或记录必须包含：输入/来源、执行动作、验证结果、阻塞/回退。

## 常见说辞

| 说辞 | 现实 | 后果 |
|------|------|------|
| "CI 红灯但只是 flaky test" | Flaky test 也是问题。修掉或移除，不能忽略红灯。 | 团队 CI 信任度在 2 周内归零，真正故障被掩盖 >60% |
| "先合并再说，CI 跑着" | CI 红灯时合并 = 明知有问题还推进。 | 修复成本从 PR 内 30min 升级到主分支 hotfix 2-4h |
| "不需要等部署，反正有监控" | 不等部署验证 = 把验证推给用户。 | 故障在用户侧暴露需 15-30min，影响 500+ 用户 |
| "Squash merge 会丢历史" | Squash 保持主分支可读。详细历史在 PR 中完整保留。 | 不 squash：3 个月后主分支历史膨胀 10x，bisect 效率下降 80% |
| "小 PR 不需要健康验证" | 一个字符的配置错误也能让服务 500。PR 大小和影响大小无关。 | 单字符 typo 导致服务中断，故障发现延迟 30min |

## 红旗

<HARD-GATE>
以下任何一个出现，立即停止：

- CI 红灯时尝试合并
- 跳过健康验证直接宣布"部署成功"
- 合并后不删除远程分支（分支泄漏）
- 7 天前的 review 未重新确认就合并
- 没有确认部署策略就开始"等部署"
- 部署超时后假设成功
- 没有回滚路径就合并
- 合并后第一小时无人关注
</HARD-GATE>

## 验证失败处理

| 失败场景 | 处理方式 |
|----------|----------|
| CI 失败 | 阻塞合并，PR 分支修复后重推，等待全绿 |
| Review 过期（>7 天） | 阻塞合并，请 human partner 重新确认 |
| 合并冲突 | PR 分支 rebase/merge base 解决，重推后等 CI |
| 部署超时 | 不假设失败，报告状态让 human partner 决定 |
| 健康检查 5xx 或超时 | 不自动回滚，报告结果建议按回滚计划操作 |

## 验证清单

- [ ] PR review 状态为 APPROVED
- [ ] CI 全部绿色（无一例外）
- [ ] Review 未过期（7 天内）
- [ ] PR body 准确描述变更
- [ ] PR 已成功合并（state=MERGED）
- [ ] 远程分支已清理
- [ ] 部署策略已检测
- [ ] 部署已成功完成
- [ ] 健康检查端点全部通过
- [ ] 新版本号已确认
- [ ] 回滚路径已验证
- [ ] Ship / Canary Carryover 已带入 `05-ship.md` 和 `06-canary-report.md` 状态
- [ ] Production Verification 已记录健康、版本、关键路径和监控证据
- [ ] Final Deployment Status 已记录 deployed / rolled-back / paused / failed
- [ ] Follow-up / Ownership 已记录剩余动作和下一命令
- [ ] 07-deploy-report.md 已生成

## 输出模板

模板起点：`templates/feature/07-deploy-report.md`

```markdown
# <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
```