cicd-setup

CI/CD 设置

适用场景

• 从零开始为新项目设置 CI
• 替换不可靠、与实际技术栈不匹配的复制粘贴式流水线配置
• 在 GitHub Actions 和 GitLab CI 平台之间迁移
• 检查流水线阶段是否与项目实际使用的工具相匹配
• 优化缓慢的构建（缓存、并行处理、条件步骤）
• 在添加专项加固措施前，建立稳定的 CI 基础

所需上下文

从 startup-context 获取：技术栈、部署目标、团队规模。还需检测或询问：

• 语言和框架（提问前先根据仓库文件自动检测）
• 部署目标（Vercel、AWS、GCP、Fly.io 等）
• CI/CD 平台（默认：GitHub Actions；也支持 GitLab CI）
• 环境（dev、staging、production）和现有测试覆盖率
• 构建或部署所需的机密和凭据

工作流

1. 根据仓库信号检测技术栈 — 扫描锁文件（package-lock.json、yarn.lock、poetry.lock、go.sum、Cargo.lock）、语言清单文件（package.json、pyproject.toml、go.mod）和脚本定义（test、lint、build 命令）。锁文件表明所用的包管理器。缺少脚本时采用保守的默认设置。切勿将 Node 假定为 Python 项目的技术栈。
2. 选择流水线阶段 — 从可靠的基础配置开始：检出代码、设置运行时、安装依赖并启用缓存，然后依次执行 lint、test、build。只有基础配置正常运行后才添加复杂内容。
3. 生成流水线配置 — 为检测到的平台编写 CI 配置。生成机器可读的 YAML，并根据检测到的包管理器设置正确的缓存策略。确认所有引用的命令都确实存在于项目中。
4. 配置机密 — 列出所需机密及其添加方法。使用平台托管的机密存储。建议使用 OIDC 进行云身份验证，而非长期密钥。切勿在 YAML 中硬编码凭据。
5. 安全地添加部署阶段 — 先仅配置 CI（lint/test/build）。添加 staging 部署时，明确说明环境信息。添加 production 部署时，设置手动审批。在发布和回滚流程中保持透明。
6. 合并前验证 — 确认生成的 YAML 语法有效、所有命令都存在于项目中、缓存与包管理器相匹配，并且分支保护符合组织要求。
7. 交付配置和说明 — 提供完整配置文件和设置步骤。

输出格式

# CI/CD Pipeline: [Project Name]
## Stack Detection Results — detected language, runtime, tools, and build commands
## Pipeline Overview — Mermaid flowchart showing stages
## Pipeline Configuration — Full YAML config file
## Secrets Required — table: name, where to get, how to add
## Setup Instructions — step-by-step to activate
## Validation Checklist — commands verified, caching confirmed, branch rules set
## Optimization Notes — caching strategy, estimated build time

框架与最佳实践

优先检测的流水线生成方式

始终先检测，再生成。检测器依赖具体的文件信号：

• 锁文件表明所用的包管理器（npm、yarn、pip、cargo、go modules）
• 语言清单文件可识别运行时系列
• package.json/pyproject.toml 中的脚本定义可用于确定 lint/test/build 命令
• 缺少脚本时，采用保守的默认命令，而不是自行假设

按生态系统划分的缓存策略

生态系统	缓存路径	缓存键
Node.js	~/.npm 或 node_modules	hashFiles('**/package-lock.json')
Python	~/.cache/pip	hashFiles('**/requirements*.txt')
Go	~/go/pkg/mod	hashFiles('**/go.sum')
Rust	~/.cargo/registry、target/	hashFiles('**/Cargo.lock')
Ruby	vendor/bundle	hashFiles('**/Gemfile.lock')

流水线架构原则

• 先运行 lint — 在耗时的测试运行前尽早失败
• 采用顺序执行的基础流程 — 检出代码、安装依赖、运行 lint、test、build，然后发布构件
• 充分利用缓存 — 将构建时间缩短 30-60%
• 固定操作版本 — 使用 SHA 哈希而非标签，以保障供应链安全
• 设置超时（timeout-minutes: 15）和并发控制，以取消重复运行
• 一次只添加一项增强 — 不要在一个 PR 中同时添加矩阵构建、安全扫描和部署

环境策略

环境	触发条件	审批	用途
CI	每次推送/PR	无	运行 lint + 测试
Staging	合并到 main	无（自动）	集成测试、QA
Production	Git 标签或手动触发	需要	面向实际用户

常见问题

1. 将针对 Node 的流水线应用于 Python 或 Go 仓库（先检测）
2. 尚未建立可靠的测试覆盖率就启用部署
3. 忽略依赖项缓存配置
4. 在次要分支更新时运行完整的矩阵构建（使用路径过滤器）
5. 在生产部署中遗漏分支保护
6. 将凭据直接嵌入流水线 YAML

扩展与平台说明

• 执行时间超过 10 分钟时，将长时间运行的作业拆分
• 仅在确实存在兼容性问题时实现测试矩阵
• 面向 GitHub 生态使用 GitHub Actions；面向自托管 SCM+CI 使用 GitLab CI
• 每个仓库维护一个唯一的规范流水线源

相关技能

• code-review — 提交前串联调用，以审查 CI 配置本身
• security-review — 串联调用，以添加或审计安全扫描阶段（trivy、semgrep、npm audit）

示例

示例提示词：“为我部署在 Vercel 上的 Next.js 应用设置 CI/CD。”

良好输出片段：

name: CI
on:
  push: { branches: [main] }
  pull_request: { branches: [main] }
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  lint:
    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 run lint && npx tsc --noEmit
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: 'npm' }
      - run: npm ci && npm test -- --coverage

示例提示词：“我的 Python CI 需要 8 分钟，如何加快速度？”

良好输出片段：

Stack detection shows: Python 3.11, pytest, pip. Three fixes to cut to ~3 minutes:
(1) Add pip caching keyed on hashFiles('requirements*.txt'),
(2) split unit/integration tests into parallel jobs,
(3) add path filters to skip CI on docs-only changes.