infra-ci-cd-github-actions

CI/CD 流水线

**快速指南：**使用 GitHub Actions 实现 CI/CD。通过受影响项检测优化 monorepo（例如 Turborepo --affected 或 --filter=...[origin/main]）。缓存依赖项和构建输出，加快 CI。质量门禁：将 lint + 类型检查 + 测试 + 构建 + 覆盖率设为必需状态检查。通过构建晋级实现多环境部署。使用 OIDC 进行云服务提供商身份验证。固定所有操作和运行时版本。

---

<critical_requirements>

重要：使用此技能前

所有代码必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入顺序、import type、命名常量）

（必须在 PR 构建中使用受影响项／已更改包检测——绝不在 PR 上运行完整测试套件）

（必须缓存包管理器依赖项和构建输出——CI 不使用缓存会浪费 70% 的运行时间）

（必须固定操作版本（actions/checkout@v6、oven-sh/setup-bun@v2、actions/cache@v5）——绝不使用 @main 或未指定版本的操作）

（必须将质量门禁（lint + 类型检查 + 测试 + 构建）设为必需状态检查——失败时阻止合并）

（支持时必须使用 OIDC 进行云服务提供商身份验证——绝不使用静态长期凭据）

</critical_requirements>

---

详细资源：

• examples/core.md - 流水线配置、作业、缓存、可复用工作流、复合操作、矩阵构建
• examples/testing.md - 受影响项检测、质量门禁
• examples/caching.md - 远程缓存、Turborepo
• examples/security.md - OIDC 身份验证、密钥轮换、工件证明
• examples/deployment.md - 多环境、回滚
• examples/monitoring.md - CI 指标、GitHub Insights
• reference.md - 决策框架、反模式、常量参考

---

**自动检测：**GitHub Actions、CI/CD 流水线、.github/workflows、Turborepo 受影响项检测、远程缓存、部署自动化、质量门禁、OIDC 身份验证、密钥轮换、工件证明、SLSA 来源证明、可复用工作流、复合操作、矩阵构建、workflow_call

适用场景：

• 为 monorepo 设置 GitHub Actions 工作流
• 实现受影响项检测，加快 PR 构建
• 配置远程缓存，共享构建工件
• 设置质量门禁和分支保护规则
• 为云部署实现 OIDC 身份验证
• 添加工件证明，保障供应链安全

不适用场景：

• 未使用 GitHub 的项目（请使用 CI 提供商的原生文档）
• 无需自动化测试或构建步骤

涵盖的关键模式：

• 配置包含并行作业和依赖项缓存的流水线
• 受影响项检测（Turborepo --affected 标志或 --filter=...[origin/main]）
• 质量门禁（lint、类型检查、测试、构建作为带依赖关系的并行作业）
• OIDC 身份验证（云服务提供商不使用静态凭据）
• 可复用工作流（workflow_call，总计最多 10 层）
• 复合操作（using: composite，共享设置逻辑）
• 矩阵构建（include/exclude、快速失败、动态矩阵）
• 工件证明（SLSA v1.0 Build Level 2 来源证明）
• 通过构建晋级实现多环境部署

---

理念

CI/CD 流水线可自动执行测试、构建和部署。在 monorepo 中，随着代码库不断增长，智能缓存和受影响项检测对于保持 CI 快速至关重要。

核心原则：

• **快速反馈：**通过受影响项检测和缓存，将 PR 构建时间控制在 5 分钟以内
• **构建一次，随处晋级：**通过同一个构建工件部署到预览、暂存和生产环境
• **不使用静态凭据：**云服务提供商使用 OIDC，轮换凭据使用密钥管理器
• **质量门禁阻止合并：**合并前，lint、类型检查、测试和构建必须全部通过

---

## 核心模式

模式 1：流水线配置

将安装、并行质量检查和构建分开。

# Recommended workflow structure:
# ci.yml      - lint, test, type-check, build (PR + main)
# deploy.yml  - production deployment from main
# preview.yml - preview deployments for PRs

关键决策：

• 固定运行时和操作的版本（切勿使用 latest）
• 设置单独的安装作业并缓存依赖项，然后分流到并行的 lint、测试和类型检查作业
• 只有所有质量关卡均通过后才进行构建
• 使用 concurrency 和 cancel-in-progress: true，避免浪费资源

完整的工作流示例请参见 examples/core.md。

---

模式 2：受影响项检测

在 monorepo 中，只测试和构建有更改的软件包。

Turborepo 示例（两种方法，择一使用）：

# Modern: --affected flag (auto-detects CI environment)
turbo run test --affected

# Manual: --filter with git comparison
turbo run test --filter=...[origin/main]

关键原则： PR 使用受影响项检测，以便快速获得反馈（< 5 分钟）。主分支运行完整套件。

注意事项： 新软件包没有 git 历史记录，会被受影响项检测跳过。务必检查是否存在新的 package.json 文件，并在发现时回退到运行完整套件。

PR 与主分支工作流示例请参见 examples/testing.md。

---

模式 3：质量关卡

合并前必须通过的自动化检查。

质量关卡顺序：

1. Lint（代码风格和静态分析）
2. 类型检查（TypeScript 错误）
3. 测试与覆盖率（功能验证）
4. 构建验证（生产构建成功）
5. Bundle 大小检查（防止性能回退）
6. 安全审计（依赖项漏洞）

将这些检查配置为分支保护中的必需状态检查。使用 strict: true，要求分支在合并前保持最新。

完整的质量关卡工作流请参见 examples/testing.md。

---

模式 4：OIDC 身份验证

消除云部署中的静态凭据。

# Key requirement for OIDC:
permissions:
  id-token: write # Required for OIDC token generation
  contents: read

OIDC 消除了： 手动轮换密钥、密钥泄露带来的永久安全风险，以及无法追踪的部署。临时凭据会自动过期（通常为 1 小时）。

AWS OIDC 和基于令牌的身份验证示例请参见 examples/security.md。

---

模式 5：可复用工作流与复合操作

在多个代码仓库之间集中管理 CI/CD 逻辑。

特性	可复用工作流	复合操作
范围	多个作业	作业内的步骤
密钥	原生支持 secrets 上下文	必须通过输入传递
嵌套	总共最多 10 层（调用方 + 9 层嵌套），每次运行最多 50 个唯一项	不适用
用途	完整流水线模板	共享的设置/清理步骤

实现示例请参见 examples/core.md。

---

性能优化

目标：PR 构建的 CI 运行时间 < 5 分钟

并行化技巧：

• 将安装作业与并行的 lint、测试和类型检查作业分开（节省 40% 的时间）
• 使用矩阵构建测试多个操作系统/版本（仅在主分支运行，不在 PR 中运行）
• 拆分测试套件（将单元测试、集成测试、端到端测试作为并行作业）
• 使用 concurrency 和 cancel-in-progress: true，取消过时的运行

监控目标：

• CI 运行时间： < 5 分钟（PR），< 10 分钟（主分支）
• 缓存命中率： > 80%（远程缓存）
• 失败率： < 5%（不包括不稳定测试）
• 部署耗时： < 10 分钟（从提交到生产环境）

---

<red_flags>

危险信号

高优先级：

• 每个 PR 都运行完整测试套件 - 使用受影响项检测，否则 CI 耗时会超过 10 分钟
• 未配置缓存 - 每次运行都重新安装依赖，浪费 2-3 分钟
• 运行时版本使用 latest - 非确定性构建会破坏可复现性
• 在密钥中存储静态云凭据 - 使用 OIDC 身份验证，切勿存储长期有效的访问密钥
• 将密钥提交到代码库 - 使用 GitHub Secrets，切勿在 YAML 中硬编码凭据
• 主分支没有质量门禁 - 缺少 lint、测试和类型检查，会导致有问题的代码合并

中优先级：

• 使用顺序执行的任务，而非并行执行 - 安装完成后，lint、测试和类型检查应并行启动
• 未设置 concurrency 限制 - 同一个 PR 上的多次 CI 运行会浪费资源
• 为每个环境重新构建 - 只构建一次，再将构建产物逐级部署到各环境
• 未监控 CI 性能 - 不跟踪耗时和缓存命中率，就无法发现瓶颈
• 工作流中存在魔法数字 - 硬编码超时和阈值，却未说明其意图

常见错误：

• 未在受影响项检测中使用 fetch-depth: 0（缺少历史记录时，git diff 会失败）
• 在每个任务上都使用 needs: [all, previous, jobs]（会导致顺序执行）
• 未处理受影响项检测中的新包（这些包会被跳过）

注意事项和边缘情况：

• 受影响项检测需要 fetch-depth: 0（浅克隆会导致 git diff 失败）
• 新包没有 Git 历史记录，因此受影响项检测会跳过它们
• actions/cache 的默认限额为每个代码库 10GB（可配置至 10TB，额外存储按 $0.07/GiB/月计费）
• OIDC 需要 id-token: write 权限，否则令牌生成会静默失败
• 环境密钥会覆盖同名的代码库密钥
• 工件证明需要 attestations: write、id-token: write 和 contents: read 权限
• 可复用工作流总共支持 10 层（调用方 + 9 层嵌套，原为 4 层），每次运行最多支持 50 个唯一工作流
• actions/create-release 已弃用 - 请改用 softprops/action-gh-release@v2
• workflow_dispatch 现在支持 25 个输入项（原为 10 个）

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循 CLAUDE.md 中的项目规范

（PR 构建必须使用受影响项/变更包检测 - 切勿在 PR 上运行完整测试套件）

（必须缓存包管理器依赖和构建输出 - 不使用缓存的 CI 会浪费 70% 的运行时间）

（必须固定操作版本（actions/checkout@v6、oven-sh/setup-bun@v2、actions/cache@v5）- 切勿使用 @main 或未指定版本的操作）

（必须将质量门禁（lint + 类型检查 + 测试 + 构建）设为必需的状态检查 - 失败时阻止合并）

（支持时必须使用 OIDC 进行云服务提供商身份验证 - 切勿使用静态长期有效凭据）

不遵守这些规则将导致 CI 运行缓慢（10 分钟以上）、出现安全漏洞（凭据泄露）以及构建失败（缺少质量门禁）。

</critical_reminders>