ci-cd-and-automation

CI/CD 和自动化

概述

自动化质量门禁，确保任何变更都必须通过测试、lint、类型检查和构建后才能进入生产环境。CI/CD 是其他所有技能的执行机制——它能发现人类和 Agent 遗漏的问题，并在每次变更中始终如一地执行检查。

左移： 尽可能在流水线的早期发现问题。lint 阶段发现一个 bug 只需几分钟；同一个 bug 若在生产环境中发现，则需要数小时。将检查前移——先做静态分析，再做测试；先测试，再部署到预发布环境；最后才进入生产环境。

越快越安全： 更小的批次和更频繁的发布会降低风险，而不是增加风险。相比包含 30 项变更的部署，包含 3 项变更的部署更容易调试。频繁发布也能增强对发布流程本身的信心。

适用场景

• 为新项目设置 CI 流水线
• 添加或修改自动化检查
• 配置部署流水线
• 变更应触发自动验证时
• 调试 CI 故障

质量门禁流水线

每项变更在合并前都必须通过以下门禁：

Pull Request Opened
    │
    ▼
┌─────────────────┐
│   LINT CHECK     │  eslint, prettier
│   ↓ pass         │
│   TYPE CHECK     │  tsc --noEmit
│   ↓ pass         │
│   UNIT TESTS     │  jest/vitest
│   ↓ pass         │
│   BUILD          │  npm run build
│   ↓ pass         │
│   INTEGRATION    │  API/DB tests
│   ↓ pass         │
│   E2E (optional) │  Playwright/Cypress
│   ↓ pass         │
│   SECURITY AUDIT │  npm audit
│   ↓ pass         │
│   BUNDLE SIZE    │  bundlesize check
└─────────────────┘
    │
    ▼
  Ready for review

不得跳过任何门禁。 如果 lint 失败，就修复 lint——不要禁用规则。如果测试失败，就修复代码——不要跳过测试。

GitHub Actions 配置

基本 CI 流水线

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npx tsc --noEmit

      - name: Test
        run: npm test -- --coverage

      - name: Build
        run: npm run build

      - name: Security audit
        run: npm audit --audit-level=high

集成数据库的测试

  integration:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: ci_user
          POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - name: Run migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
      - name: Integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb

注意： 即使是仅用于 CI 测试的数据库，也应使用 GitHub Secrets 存储凭据，而不是将值硬编码。这样可以养成良好习惯，避免在其他场景中意外复用测试凭据。

E2E 测试

  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - name: Install Playwright
        run: npx playwright install --with-deps chromium
      - name: Build
        run: npm run build
      - name: Run E2E tests
        run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

将 CI 故障反馈给 Agent

CI 与 AI Agent 协作的关键在于反馈循环。当 CI 失败时：

CI fails
    │
    ▼
Copy the failure output
    │
    ▼
Feed it to the agent:
"The CI pipeline failed with this error:
[paste specific error]
Fix the issue and verify locally before pushing again."
    │
    ▼
Agent fixes → pushes → CI runs again

关键模式：

Lint failure → Agent runs `npm run lint --fix` and commits
Type error  → Agent reads the error location and fixes the type
Test failure → Agent follows debugging-and-error-recovery skill
Build error → Agent checks config and dependencies

部署策略

预览部署

每个 PR 都会获得一个预览部署，用于手动测试：

# Deploy preview on PR (Vercel/Netlify/etc.)
deploy-preview:
  runs-on: ubuntu-latest
  if: github.event_name == 'pull_request'
  steps:
    - uses: actions/checkout@v4
    - name: Deploy preview
      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}

功能开关

功能开关将部署与发布分离。将未完成或有风险的功能置于开关后再部署，这样你就可以：

• 发布代码但不启用功能。 尽早合并到 main，准备就绪后再启用。
• 无需重新部署即可回滚。 禁用开关，而不是回退代码。
• 对新功能进行金丝雀发布。 先向 1% 的用户启用，再扩大到 10%，最后达到 100%。
• 运行 A/B 测试。 比较启用和未启用该功能时的行为。

// Simple feature flag pattern
if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
  return renderNewCheckout();
}
return renderLegacyCheckout();

开关生命周期： 创建 → 启用以供测试 → 金丝雀发布 → 全面推出 → 移除开关和无用代码。长期存在的开关会成为技术债务——创建时就设定清理日期。

分阶段发布

PR merged to main
    │
    ▼
  Staging deployment (auto)
    │ Manual verification
    ▼
  Production deployment (manual trigger or auto after staging)
    │
    ▼
  Monitor for errors (15-minute window)
    │
    ├── Errors detected → Rollback
    └── Clean → Done

回滚计划

每次部署都应可逆：

# Manual rollback workflow
name: Rollback
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to rollback to'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - name: Rollback deployment
        run: |
          # Deploy the specified previous version
          npx vercel rollback ${{ inputs.version }}

环境管理

.env.example       → Committed (template for developers)
.env                → NOT committed (local development)
.env.test           → Committed (test environment, no real secrets)
CI secrets          → Stored in GitHub Secrets / vault
Production secrets  → Stored in deployment platform / vault

CI 中绝不能包含生产环境机密。CI 测试应使用单独的机密。

CI 之外的自动化

Dependabot / Renovate

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    open-pull-requests-limit: 5

构建负责人职责

指定一名负责人，确保 CI 始终保持通过状态。构建失败时，构建负责人的职责是修复问题或回退变更，而不是由导致故障的变更提交者负责。这样可以避免构建故障不断累积，同时所有人都以为别人会处理。

PR 检查

• 必需审查： 合并前至少获得 1 个批准
• 必需状态检查： 合并前 CI 必须通过
• 分支保护： 禁止强制推送到 main
• 自动合并： 所有检查通过且获得批准后，自动合并

CI 优化

当流水线耗时超过 10 分钟时，按影响程度从高到低应用以下策略：

Slow CI pipeline?
├── Cache dependencies
│   └── Use actions/cache or setup-node cache option for node_modules
├── Run jobs in parallel
│   └── Split lint, typecheck, test, build into separate parallel jobs
├── Only run what changed
│   └── Use path filters to skip unrelated jobs (e.g., skip e2e for docs-only PRs)
├── Use matrix builds
│   └── Shard test suites across multiple runners
├── Optimize the test suite
│   └── Remove slow tests from the critical path, run them on a schedule instead
└── Use larger runners
    └── GitHub-hosted larger runners or self-hosted for CPU-heavy builds

示例：缓存和并行处理

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npm run lint

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npx tsc --noEmit

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npm test -- --coverage

常见借口

借口	事实
“CI 太慢了”	优化流水线（参见下文的 CI 优化），不要跳过。5 分钟的流水线可以避免数小时的调试。
“这个改动微不足道，跳过 CI 吧”	微小改动也会导致构建失败。而且，针对微小改动，CI 本来就很快。
“这个测试不稳定，重跑一下就行”	不稳定的测试会掩盖真正的错误，还会浪费所有人的时间。修复不稳定问题。
“我们以后再添加 CI”	没有 CI 的项目会不断积累故障状态。第一天就配置好。
“手动测试就够了”	手动测试无法扩展，也无法重复执行。尽可能自动化。

危险信号

• 项目中没有 CI 流水线
• 忽视或屏蔽 CI 失败
• 为了让流水线通过而在 CI 中禁用测试
• 未经预发布验证就部署到生产环境
• 没有回滚机制
• 将密钥存放在代码或 CI 配置文件中（而不是密钥管理器中）
• CI 耗时很长，却没有进行任何优化

验证

设置或修改 CI 后：

• 已包含所有质量门禁（lint、类型检查、测试、构建、审计）
• 每次 PR 和向 main 推送时都会运行流水线
• 失败会阻止合并（已配置分支保护）
• CI 结果会反馈到开发循环中
• 密钥存储在密钥管理器中，而不是代码中
• 部署具备回滚机制
• 测试套件的流水线运行时间不超过 10 分钟