ci-cd-patterns

CI/CD 模式

适用于 GitHub Actions、PR 自动化和部署工作流的模式。

适用场景

• 设置或修复 GitHub Actions 工作流
• 自动执行 PR 检查（lint、test、build）
• 配置部署流水线
• 监控 PR 状态并重试不稳定的 CI
• 设置多环境部署（dev、staging、prod）

GitHub Actions --- 常见模式

基本 CI 工作流

name: CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: ./gradlew test

PR 检查工作流

name: PR Check
on: pull_request

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./gradlew ktlintCheck

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./gradlew test

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - run: ./gradlew build

PR 跟进模式

在 CI 运行期间监控 PR，并处理常见故障：

1. 检查 CI 状态 --- gh pr checks <number>
2. 确定故障类型 --- 不稳定的测试、lint 错误、构建失败
3. 修复并推送 --- 对于 lint 或构建错误，在本地修复后推送
4. 重试不稳定的测试 --- 重新运行工作流：gh run rerun <run-id> --failed
5. 解决合并冲突 --- 变基到目标分支
6. 启用自动合并 --- gh pr merge <number> --auto --squash

请参阅 workflows.md，获取可直接使用的 GitHub Actions YAML 模板。

部署检查清单

部署前：

• 所有 CI 检查均已通过
• 没有合并冲突
• 已审核数据库迁移（如有）
• 已在目标环境中设置环境变量
• 已确定回滚方案

注意事项

• 缓存每次运行可节省数分钟。 始终缓存依赖项（使用 actions/cache，或为 actions/setup-java 启用缓存）。冷启动的 Gradle 构建需要 3-5 分钟，使用缓存只需 30 秒。
• needs: 会创建顺序依赖。 如果不使用它，所有作业都会并行运行。使用 needs: [lint, test]，让构建等待检查完成。
• 密钥名称区分大小写。 secrets.DB_PASSWORD 和 secrets.db_password 是不同的。请与 Settings > Secrets 中的名称完全一致。
• 不要使用 actions/checkout@v3 --- 请使用 v4。 v3 使用已弃用的 Node 16，v4 使用 Node 20。
• 不稳定的测试需要调查，而不只是重试。 如果同一个测试的工作流重跑超过两次，请修复该测试。常见原因包括竞态条件、依赖时间的断言和共享的测试状态。
• 在 CI 审查期间强制推送会重置检查套件。 请等 CI 完成后再强制推送，否则会浪费运行器时间。

规则

• 每个 PR 都必须通过 CI 才能合并
• 除非只涉及文档，否则不要跳过 CI 检查（[skip ci]）
• 将工作流总运行时间控制在 10 分钟以内
• 使用矩阵构建进行多版本测试
• 将密钥存储在 GitHub Secrets 中，切勿写入代码