19c - AI 辅助 CI/CD 配置

你的代码托管在哪里？
│
├── GitHub
│   ├── 需要 AI Agent 自主处理 PR？ → GitHub Agentic Workflows
│   ├── 需要基础 CI/CD？ → GitHub Actions
│   └── 构建太慢？ → GitHub Actions + Blacksmith/Depot
│
├── GitLab
│   ├── 企业级 DevSecOps？ → GitLab CI + Duo（Premium/Ultimate）
│   └── 免费层够用？ → GitLab CI 免费版
│
├── 多平台 / 需要深度优化
│   └── → CircleCI + Chunk AI Agent
│
└── 自托管需求
    ├── GitHub 生态？ → GitHub Actions Self-hosted Runners
    └── GitLab 生态？ → GitLab Runner 自托管

# CLAUDE.md 或 .cursorrules 中添加 CI/CD 上下文
 
## CI/CD 规范
- 平台：GitHub Actions
- 运行环境：ubuntu-latest
- Node.js 版本：20.x（LTS）
- 包管理器：pnpm 9.x
- 测试框架：Vitest
- 代码检查：ESLint + Prettier
- 部署目标：Vercel（预览）/ AWS（生产）
- 分支策略：main（生产）、develop（开发）、feature/*（功能）

请为我的 [语言/框架] 项目生成 GitHub Actions CI 工作流，要求：

项目信息：
- 语言：[TypeScript/Python/Rust/Go]
- 包管理器：[pnpm/yarn/pip/cargo]
- 测试框架：[Vitest/Jest/Pytest/cargo test]
- 代码检查：[ESLint/Ruff/clippy]

工作流要求：
1. 触发条件：push 到 main/develop，PR 到 main
2. 缓存依赖（使用 [包管理器] 缓存）
3. 并行运行 lint、test、build
4. 测试覆盖率报告上传
5. 仅在 main 分支触发部署

安全要求：
- 使用 OIDC 认证云服务（不用长期密钥）
- 最小权限 permissions 声明
- 第三方 Action 锁定 SHA 版本

请生成完整的 .github/workflows/ci.yml 文件。

name: CI
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
permissions:
  contents: read
  pull-requests: write
 
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
 
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test -- --coverage
      - uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/
 
  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
 
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    needs: [build]
    permissions:
      id-token: write  # OIDC 认证所需
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ap-northeast-1
      - run: echo "部署到生产环境..."

传统 CI/CD（确定性）：
  触发 → 步骤 1 → 步骤 2 → 步骤 3 → 结果
  （固定路径，if/then 逻辑）

Agentic Workflows（非确定性）：
  触发 → AI Agent 分析上下文 → 推理决策 → 执行操作 → 验证结果
  （动态路径，基于理解和推理）

# .github/workflows/agentic-review.yml
name: Agentic Code Review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: AI Code Review
        uses: github/copilot-agentic-action@v1  # 技术预览
        with:
          model: copilot
          prompt: |
            审查这个 PR 的代码变更，关注：
            1. 安全漏洞（SQL 注入、XSS、密钥泄露）
            2. 性能问题（N+1 查询、内存泄漏）
            3. 代码风格一致性
            4. 测试覆盖率是否充分
            提供具体的改进建议。

GitLab Duo Agent Platform 架构：

开发者 ←→ Duo Chat（统一入口）
              │
    ┌─────────┼─────────┐
    ▼         ▼         ▼
 代码 Agent  安全 Agent  CI/CD Agent
 (重构/审查) (扫描/修复) (配置/优化)
    │         │         │
    └─────────┼─────────┘
              ▼
        GitLab 平台 API

请为我的 [语言/框架] 项目生成 .gitlab-ci.yml 配置，要求：

项目信息：
- 语言：[Python/TypeScript/Go/Java]
- 构建工具：[pip/pnpm/go build/Maven]
- 测试框架：[Pytest/Vitest/go test/JUnit]
- 容器化：[是/否]

流水线要求：
1. 阶段：lint → test → build → deploy
2. 使用 GitLab CI 缓存加速依赖安装
3. 并行测试（使用 parallel 关键字）
4. 环境区分：staging（develop 分支）、production（main 分支）
5. 手动审批生产部署

安全要求：
- 使用 GitLab CI/CD Variables（masked + protected）
- SAST 和依赖扫描集成
- 容器扫描（如果使用 Docker）

请生成完整的 .gitlab-ci.yml 文件，包含注释说明。

# .gitlab-ci.yml
stages:
  - lint
  - test
  - build
  - deploy
 
variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
  DOCKER_IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
 
# 全局缓存配置
cache:
  key:
    files:
      - requirements.txt
      - requirements-dev.txt
  paths:
    - .pip-cache/
    - .venv/
 
# ---- Lint 阶段 ----
ruff-lint:
  stage: lint
  image: python:3.12-slim
  script:
    - pip install ruff
    - ruff check .
    - ruff format --check .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_BRANCH == "develop"
 
# ---- Test 阶段 ----
unit-tests:
  stage: test
  image: python:3.12-slim
  parallel: 3  # 并行 3 个测试分片
  script:
    - python -m venv .venv
    - source .venv/bin/activate
    - pip install -r requirements-dev.txt
    - pytest tests/ --splits $CI_NODE_TOTAL --group $CI_NODE_INDEX
        --cov=app --cov-report=xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml
    expire_in: 7 days
 
# GitLab SAST 扫描（内置模板）
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
 
# ---- Build 阶段 ----
build-image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $DOCKER_IMAGE .
    - docker push $DOCKER_IMAGE
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_BRANCH == "develop"
 
# ---- Deploy 阶段 ----
deploy-staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
  script:
    - echo "部署到 staging..."
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
 
deploy-production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  script:
    - echo "部署到 production..."
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  when: manual  # 手动审批

流水线失败
    │
    ▼
AI 自动分析失败日志
    │
    ▼
识别根本原因（依赖冲突/语法错误/环境问题/flaky 测试）
    │
    ▼
生成修复建议或直接创建修复 MR
    │
    ▼
开发者审查并合并

1. 在 CircleCI Web App 侧边栏找到 Chunk
2. 点击 "Set up Chunk" 并授权 GitHub 访问
3. 连接 Anthropic 或 OpenAI API Key
4. Chunk 开始分析你的仓库和流水线配置

Chunk 分析流程：
  1. 扫描 .circleci/config.yml
  2. 分析最近 30 天的构建历史
  3. 识别瓶颈（慢步骤、缓存未命中、串行执行）
  4. 生成优化 PR（包含详细说明）
  5. 开发者审查并合并

请为我的 [语言/框架] 项目生成 .circleci/config.yml，要求：

项目信息：
- 语言：[TypeScript/Python/Go]
- 包管理器：[pnpm/pip/go modules]
- 测试框架：[Vitest/Pytest/go test]
- Docker 构建：[是/否]

优化要求：
1. 使用 CircleCI Orbs 简化配置
2. 依赖缓存（基于 lockfile hash）
3. 测试并行化（使用 parallelism）
4. 工作流编排（fan-out/fan-in 模式）
5. 资源类（resource_class）优化

请生成完整配置，包含注释。

# 方式 1：使用 setup-node 内置缓存（推荐）
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'pnpm'
 
# 方式 2：精细控制缓存（大型项目）
- uses: actions/cache@v4
  id: deps-cache
  with:
    path: |
      node_modules
      ~/.pnpm-store
    key: deps-${{ runner.os }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
    restore-keys: |
      deps-${{ runner.os }}-pnpm-
 
# 方式 3：构建产物缓存（Turbo/Nx 等 monorepo 工具）
- uses: actions/cache@v4
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ github.sha }}
    restore-keys: |
      turbo-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
      turbo-${{ runner.os }}-

分析以下 CI/CD 配置的缓存策略，提出优化建议：

[粘贴你的 workflow YAML]

请关注：
1. 缓存键是否足够精确（避免缓存失效过频）
2. 缓存键是否有 fallback（restore-keys）
3. 是否有遗漏的可缓存内容（构建产物、编译缓存）
4. 缓存大小是否合理（避免超出平台限制）
5. 是否可以使用平台内置缓存替代手动配置

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false  # 一个失败不取消其他
      matrix:
        node-version: [18, 20, 22]
        os: [ubuntu-latest, macos-latest]
        shard: [1, 2, 3, 4]  # 测试分片
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: pnpm install --frozen-lockfile
      - run: pnpm test -- --shard=${{ matrix.shard }}/4

unit-tests:
  stage: test
  parallel: 4  # 自动分配 CI_NODE_INDEX 和 CI_NODE_TOTAL
  script:
    - pytest tests/ --splits $CI_NODE_TOTAL --group $CI_NODE_INDEX

        ┌── lint ──┐
        │          │
trigger ├── test ──┤── build ── deploy
        │          │
        └── scan ──┘
     (fan-out)   (fan-in)

# GitHub Actions fan-out/fan-in
jobs:
  lint:
    runs-on: ubuntu-latest
    steps: [...]
 
  test:
    runs-on: ubuntu-latest
    steps: [...]
 
  security-scan:
    runs-on: ubuntu-latest
    steps: [...]
 
  build:
    needs: [lint, test, security-scan]  # fan-in：等待所有并行任务完成
    runs-on: ubuntu-latest
    steps: [...]

# GitHub Actions：取消同分支的旧运行
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 
# 生产部署例外：不取消正在进行的部署
concurrency:
  group: deploy-production
  cancel-in-progress: false

密钥管理成熟度模型：

Level 0：硬编码在代码中（❌ 绝对禁止）
Level 1：CI/CD 平台内置 Secrets（✅ 基础）
Level 2：外部密钥管理器（HashiCorp Vault / AWS Secrets Manager）（✅✅ 推荐）
Level 3：OIDC 短期令牌，零长期密钥（✅✅✅ 最佳）

# 步骤 1：在 AWS 中配置 OIDC Identity Provider
# 步骤 2：创建 IAM Role 并信任 GitHub OIDC Provider
# 步骤 3：在工作流中使用
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # 必须：请求 OIDC 令牌
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Configure AWS Credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
          aws-region: ap-northeast-1
          # 无需 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY！
      - run: aws s3 sync ./dist s3://my-bucket

deploy:
  stage: deploy
  image: amazon/aws-cli:latest
  id_tokens:
    AWS_TOKEN:
      aud: https://gitlab.com  # OIDC audience
  script:
    - >
      STS_RESPONSE=$(aws sts assume-role-with-web-identity
        --role-arn $AWS_ROLE_ARN
        --role-session-name "gitlab-ci-$CI_PIPELINE_ID"
        --web-identity-token $AWS_TOKEN
        --duration-seconds 900)
    - export AWS_ACCESS_KEY_ID=$(echo $STS_RESPONSE | jq -r '.Credentials.AccessKeyId')
    - export AWS_SECRET_ACCESS_KEY=$(echo $STS_RESPONSE | jq -r '.Credentials.SecretAccessKey')
    - export AWS_SESSION_TOKEN=$(echo $STS_RESPONSE | jq -r '.Credentials.SessionToken')
    - aws s3 sync ./dist s3://my-bucket

密钥管理清单：

□ 使用 OIDC 替代长期凭证（AWS、GCP、Azure 均支持）
□ CI/CD Secrets 设置为 masked（日志中不可见）
□ 生产环境 Secrets 设置为 protected（仅受保护分支可用）
□ 定期轮换密钥（30-90 天）
□ 使用 GitGuardian 或 gitleaks 扫描密钥泄露
□ 第三方 Action/Job 使用 SHA 锁定版本（防止供应链攻击）
□ 最小权限原则：每个工作流只授予必要的权限
□ 环境隔离：staging 和 production 使用不同的密钥集

请审查以下 CI/CD 配置的密钥管理安全性：

[粘贴你的 workflow YAML]

请检查：
1. 是否有硬编码的密钥或凭证
2. 是否可以用 OIDC 替代长期密钥
3. permissions 声明是否遵循最小权限原则
4. 第三方 Action 是否锁定了 SHA 版本
5. 密钥是否正确使用了 masked/protected 属性
6. 是否有密钥通过环境变量泄露到日志的风险
7. fork PR 是否能访问到 secrets

请给出具体的安全改进建议和修改后的配置。

请为以下 monorepo 生成 GitHub Actions CI 配置：

仓库结构：
├── apps/
│   ├── web/          # Next.js 前端
│   ├── api/          # Node.js 后端
│   └── mobile/       # React Native
├── packages/
│   ├── ui/           # 共享 UI 组件
│   └── utils/        # 共享工具库
└── pnpm-workspace.yaml

要求：
1. 路径过滤：只在相关目录变更时触发对应任务
2. 共享依赖安装步骤（使用 composite action 或 reusable workflow）
3. 各应用独立测试和构建
4. 共享包变更时触发所有依赖应用的测试

请为 Rust 项目生成 GitHub Actions CI 配置：

要求：
1. 使用 Swatinem/rust-cache 缓存编译产物
2. 并行运行：clippy lint、cargo test、cargo build --release
3. 交叉编译：Linux (x86_64, aarch64)、macOS (x86_64, aarch64)、Windows (x86_64)
4. 使用 matrix 策略管理多平台构建
5. Release 时自动创建 GitHub Release 并上传二进制文件

我的 CI/CD 流水线失败了，请帮我分析原因并提供修复方案。

平台：[GitHub Actions / GitLab CI / CircleCI]
失败的 Job：[job 名称]
错误日志：

配置文件：
```yaml
[粘贴相关的 workflow YAML]

---

## 实战案例：从零构建 AI 辅助 CI/CD 流水线

### 场景：全栈 SaaS 项目的 CI/CD 搭建

一个 Solo Founder 使用 Next.js + FastAPI + PostgreSQL 构建 SaaS 产品，需要搭建完整的 CI/CD 流水线。

### 工作流

### 最终配置结构

### 关键决策

| 决策点 | 选择 | 理由 |
|--------|------|------|
| CI/CD 平台 | GitHub Actions | 代码在 GitHub，生态集成最好 |
| 缓存策略 | pnpm 内置 + Turbo 缓存 | 最小配置，最大效果 |
| 密钥管理 | OIDC + GitHub Secrets | 零长期密钥，安全性最高 |
| 部署策略 | 预览（PR）→ staging（develop）→ production（main） | 渐进式验证 |
| 安全扫描 | CodeQL + Dependabot + gitleaks | 全免费，覆盖代码+依赖+密钥 |
| AI 辅助 | Copilot 生成 + 手动优化 | 生成初始配置后人工审查调优 |

### 优化效果

---

## 避坑指南

### ❌ 常见错误

1. **AI 生成的工作流使用 `permissions: write-all`**
   - 问题：AI 为了确保"能用"，倾向于授予最大权限，这违反最小权限原则，增加供应链攻击风险
   - 正确做法：明确声明每个 job 需要的最小权限（`contents: read`、`pull-requests: write` 等）

2. **第三方 Action 使用标签版本而非 SHA**
   - 问题：`uses: some-action@v1` 可能被恶意更新（标签可以被移动），导致供应链攻击
   - 正确做法：使用完整 SHA 锁定版本 `uses: some-action@a1b2c3d4...`，并在注释中标注版本号

3. **在 PR 工作流中暴露 Secrets 给 Fork**
   - 问题：`pull_request_target` 事件可以访问 secrets，恶意 fork 可能窃取凭证
   - 正确做法：对 fork PR 使用 `pull_request` 事件（无 secrets 访问），仅在可信分支使用 `pull_request_target`

4. **缓存键过于宽泛或过于精确**
   - 问题：键太宽泛（如 `cache-v1`）导致缓存污染；键太精确（如包含 `github.sha`）导致永远不命中
   - 正确做法：使用 lockfile hash 作为主键，OS 作为前缀，配合 `restore-keys` 实现渐进匹配

5. **不设置 `concurrency` 导致资源浪费**
   - 问题：快速连续推送时，旧的运行不会被取消，浪费 CI 分钟数和运行器资源
   - 正确做法：设置 `concurrency` 组并启用 `cancel-in-progress: true`（部署 job 除外）

6. **AI 生成的 Docker 构建不使用多阶段和层缓存**
   - 问题：每次构建都从头开始，构建时间长且镜像体积大
   - 正确做法：使用多阶段构建 + `docker/build-push-action` 的 `cache-from`/`cache-to` 参数

### ✅ 最佳实践

1. 将 CI/CD 上下文写入 Steering 规则，让 AI 从一开始就生成符合团队规范的配置
2. 使用 Reusable Workflows 或 Composite Actions 消除重复配置
3. 生产部署始终要求手动审批（`when: manual` 或 `environment` 保护规则）
4. 定期审查 CI/CD 配置的安全性，特别是权限声明和密钥使用
5. 监控构建时间趋势，当 CI 时间超过 5 分钟时主动优化

---

## 相关资源与延伸阅读

- [GitHub Agentic Workflows 官方文档](https://github.github.io/gh-aw/index.html)：GitHub Agentic Workflows 技术预览官方指南
- [GitLab Duo Agent Platform](https://about.gitlab.com/blog/gitlab-duo-agent-platform-public-beta/)：GitLab Duo Agent Platform 公测介绍
- [CircleCI Chunk AI Agent](https://circleci.com/chunk/)：CircleCI Chunk AI Agent 产品页面
- [GitHub Actions 安全加固指南](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-for-github-actions)：GitHub 官方安全最佳实践
- [GitHub OIDC 配置指南](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers)：GitHub Actions OIDC 认证配置
- [GitGuardian CI/CD 密钥管理指南](https://blog.gitguardian.com/handle-secrets-in-ci-cd-pipelines/)：CI/CD 流水线密钥安全最佳实践
- [Gradle Universal Cache](https://gradle.com/blog/universal-cache-keeps-builds-fast-and-costs-in-control/)：AI 时代的构建缓存策略

---

## 参考来源

- [GitHub — Agentic Workflows Technical Preview](https://github.github.io/gh-aw/index.html)（2026-02）
- [The Register — GitHub previews Agentic Workflows](https://www.theregister.com/2026/02/17/github_previews_agentic_workflows/)（2026-02）
- [GitLab — GitLab 18 AI-Native Capabilities](https://about.gitlab.com/press/releases/2025-05-15-gitlab-announces-gitlab-18-with-ai-native-capabilities-to-increase-developer-productivity/)（2025-05）
- [GitLab — Duo Agent Platform Public Beta](https://about.gitlab.com/blog/gitlab-duo-agent-platform-public-beta/)（2025-07）
- [GitLab — 18.4 AI-Native Development](https://about.gitlab.com/blog/gitlab-18-4-ai-native-development-with-automation-and-insight/)（2025-09）
- [CircleCI — Introducing Chunk: The Agent That Validates Code at AI Speed](https://circleci.com/blog/introducing-chunk/)（2025-06）
- [CircleCI — Optimize Your CI/CD Pipeline with Chunk AI Agent](https://circleci.com/blog/optimize-your-ci-cd-pipeline-with-circleci-chunk-ai-agent/)（2025-12）
- [Blacksmith — Best Practices for Managing Secrets in GitHub Actions](https://www.blacksmith.sh/blog/best-practices-for-managing-secrets-in-github-actions)（2025-01）
- [WarpBuild — Your CI Wasn't Built for AI-Assisted Development](https://www.warpbuild.com/blog/ai-assisted-development-ci-infrastructure)（2026-02）
- [ALM Toolbox — GitLab 2025 Release Highlights](https://www.almtoolbox.com/blog/gitlab-2025-release-highlights-ai-cicd-devsecops/)（2025）

Content was rephrased for compliance with licensing restrictions.

---

> 📖 返回 [总览与导航](../00-总览与导航.md) | 上一节：[AI 辅助 IaC 生成](./19b-AI辅助IaC生成.md) | 下一节：[AIOps 实践](./19d-AIOps实践.md)