CI/CD — 持续集成与持续部署

入口/出口

• 入口: 新项目需要 CI、现有 CI 需要修改、部署自动化配置
• 出口: 工作管道定义 + 所有质量门通过
• 指向: CI/CD 配置完成后继续 /ship 流程
• 前置加载: CANON.md
• 输出路径: 工作管道定义 + 所有质量门通过 → ship-workflow-ship（继续发布流程）

何时不使用

• 只是运行现有 CI 或查看一次构建结果
• 项目没有新增/修改自动化流水线、质量门或部署流程
• 发布决策或上线验证是主要问题（使用 ship-workflow-ship / ship-infrastructure-deploy）

Iron Law

<HARD-GATE>

每个质量门必须阻塞合并。
CI 红灯 + 合并 = 把已知问题推给下一个人。
没有缓存的 CI 是浪费分钟数。

</HARD-GATE>

核心原则

Shift Left

问题越早发现成本越低。 在 PR 中捕获比在 staging 捕获便宜 10x，比在生产捕获便宜 100x。

Faster is Safer

更小批次 + 更频繁发布 = 风险更低。 大爆炸发布 = 大爆炸回滚。

Quality Gate 流水线

Lint ──→ Type Check ──→ Unit Tests ──→ Build ──→ Integration Tests ──→ E2E Tests ──→ Security Audit ──→ Bundle Size
  │          │              │            │             │                  │                │                │
  ▼          ▼              ▼            ▼             ▼                  ▼                ▼                ▼
 代码风格  类型安全    单元行为    可构建    跨组件交互    关键用户流程    OWASP/CVE        不超过预算

任何门失败 → 管道停止 → 反馈给开发者

不设可跳过的门。 每道门都必须通过才能到下一道。

GitHub Actions 配置

name: CI
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run lint
      - run: npm run type-check
      - run: npm test -- --coverage
      - run: npm run build

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm audit --audit-level=high  # 有 high/critical → 失败

好/坏 CI 配置对照

坏 CI 配置 — 绝不能这样写：

# Bad: 无缓存、允许失败、密钥硬编码、无超时
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout
      - run: npm install
      - run: npm test
        continue-on-error: true  # 测试失败也继续！
      - run: npm run deploy
        env:
          AWS_SECRET_KEY: abc123hardcoded  # 密钥硬编码！

好 CI 配置 — 参照这个标准：

# Good: 缓存、严格失败、密钥安全、超时、分离关注点
jobs:
  lint-and-typecheck:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run lint
      - run: npx tsc --noEmit

  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm test -- --coverage
      - uses: codecov/codecov-action@v4

  deploy:
    needs: [lint-and-typecheck, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - run: npm run deploy
        env:
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}

反模式修复表

CI 失败的反馈循环

CI 失败 → 输出必须告诉开发者：

1. 什么失败了（Lint？Type？Test？）
2. 哪一行/哪个文件
3. 怎么修复（命令提示）

# CI 配置加：失败时跑特定诊断
- name: Debug test failures
  if: failure()
  run: cat test-results.xml | grep -A 5 "failure"

部署策略

最低要求:

• 每个部署必须有对应的回滚方案（命令或一键按钮）
• Staging 部署必须在生产部署之前
• Feature Flag 用于解耦部署（上线代码）和发布（启用功能）

CI 优化

CI 慢 (>10 min)？
├── 缓存 node_modules (.npm / actions/cache)
├── 测试并行 (按模块分 job)
├── 使用本地 CI runner (而非 GitHub hosted)
├── 仅跑受影响的测试 (test impact analysis)
└── 拆分 heavy job (lint + type 并行)

常见说辞

违反字面规则就是违反精神。 没有灰色地带。

红旗 — STOP

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

• 某个 CI 门被跳过/注释掉/设为 allow_failure
• 密钥直接写在 CI yaml 中（用 GitHub Secrets / Vault）
• CI 中 npm audit 有 high/critical 但未处理
• 没有自动回滚机制的手动部署
• E2E 测试在 CI 中被禁用（太慢 → 并行化或给更多 CI 资源，不禁用）
• CI 配置中没有缓存导致每次都重新安装（浪费 CI 分钟数）

注意来自人类伙伴的信号：

• "CI 过了吗？" — 你可能没等 CI 结果
• "构建要多久？" — CI 太慢需要优化
• "能不能跳过安全检查就这一次？" — 绝不能。这是红旗。
• "为什么 CI 挂了？" — 你需要读错误日志而不是猜测

</HARD-GATE>

验证失败处理

输出模板

# CI/CD Pipeline Report — 持续集成与持续部署管道报告

## 元信息
- **配置者**: [姓名/角色]
- **项目**: [项目名]
- **配置日期**: YYYY-MM-DD
- **平台**: [GitHub Actions / GitLab CI / 其他]

## Quality Gate 状态

| Gate | 状态 | 阈值 | 实际值 | 备注 |
|------|------|------|--------|------|
| Lint | ✅ / ❌ | 零 error | [实际 error 数] | — |
| Type Check | ✅ / ❌ | 零 error | [实际 error 数] | — |
| Unit Tests | ✅ / ❌ | 覆盖率 ≥ 80% | [实际覆盖率] | — |
| Build | ✅ / ❌ | 成功构建 | [构建时间] | — |
| Integration Tests | ✅ / ❌ | 全部通过 | [通过/总数] | — |
| E2E Tests | ✅ / ❌ | 关键路径通过 | [通过/总数] | — |
| Security Audit | ✅ / ❌ | zero high/critical CVE | [high/critical 数] | — |
| Bundle Size | ✅ / ❌ | ≤ [预算]KB | [实际大小]KB | — |

## CI 配置清单
- [ ] 缓存配置（node_modules/.cache）
- [ ] 所有 job 有 timeout-minutes
- [ ] 密钥使用 Secrets（无硬编码）
- [ ] Action 版本固定（@v4 或 @sha256，非 @main）
- [ ] 失败时输出诊断信息

## 部署策略
- **策略类型**: [Preview / Blue-Green / Staged Rollout / Rolling Update]
- **Staging 先于生产**: ✅ / ❌
- **回滚方案**: [描述或命令]
- **Feature Flag**: ✅ 已配置 / ❌ 未配置

## 性能指标
- **总 CI 运行时间**: [分钟]
- **关键路径时间**: [分钟]
- **优化建议**: [如有 > 10min，列出优化方向]

## 审查结论
- **通过**: 所有质量门 ✅ + 部署策略明确 + 回滚方案就绪
- **阻止**: 任何质量门 ❌ 或回滚方案缺失

## 验证清单

- [ ] 所有质量门在 CI 中启用且必须通过
- [ ] CI 配置文件已提交（无密钥硬编码）
- [ ] 依赖缓存配置（node_modules/.cache）
- [ ] 部署策略明确（Preview / Blue-Green / Staged）
- [ ] 每个部署有回滚方案
- [ ] CI 失败输出包含具体诊断信息
- [ ] Staging 先于生产部署