cicd-pipeline-generator

CI/CD 流水线生成器

概述

为各种平台（GitHub Actions、GitLab CI、CircleCI、Jenkins）生成可用于生产环境的 CI/CD 流水线配置文件。此技能提供模板和指导，帮助为现代 Web 应用（尤其是 Node.js/Next.js 项目）设置可处理代码检查、测试、构建和部署的自动化工作流。

核心功能

1. 平台选择

根据项目需求选择合适的 CI/CD 平台：

• GitHub Actions：最适合托管在 GitHub 上且需要原生集成的项目
• GitLab CI/CD：适用于流水线需求复杂的 GitLab 仓库
• CircleCI：针对 Docker 工作流和快速构建进行了优化
• Jenkins：适用于可自托管且高度可定制的环境

请参阅 references/platform-comparison.md，了解详细的平台比较、优缺点和用例建议。

2. 生成流水线配置

按照以下原则生成流水线配置：

流水线阶段

使用以下标准阶段构建流水线：

1. 安装依赖

   • 从仓库检出代码
   • 设置运行时环境（Node.js 版本）
   • 恢复缓存的依赖项
   • 使用 npm ci 安装依赖项
   • 缓存依赖项以供后续运行使用

2. 代码检查

   • 运行 ESLint，检查代码质量
   • 运行 TypeScript 类型检查
   • 遇到代码检查错误时立即失败

3. 测试

   • 执行单元测试
   • 执行集成测试
   • 生成代码覆盖率报告
   • 将覆盖率报告上传至报告服务（Codecov、Coveralls）

4. 构建

   • 创建生产构建
   • 验证构建是否成功
   • 存储构建产物

5. 部署

   • 部署到预发布环境（develop 分支）
   • 部署到生产环境（main 分支）
   • 运行部署后的冒烟测试

缓存策略

实施有效的缓存策略以加快构建速度：

# Cache node_modules based on package-lock.json
cache:
  key: ${{ hashFiles('package-lock.json') }}
  paths:
    - node_modules/
    - .npm/

环境变量

配置所需的环境变量：

• NODE_ENV：构建时设为 production
• 平台专属令牌：作为机密信息存储
• 构建时变量：传递给构建流程

3. 使用模板

使用 assets/ 目录中的模板：

GitHub Actions 模板（assets/github-actions-nodejs.yml）：

• 包含代码检查、测试、构建和部署的多任务工作流
• 支持多个 Node.js 版本的矩阵构建（可选）
• 集成 Vercel 部署
• 上传构建产物
• 报告代码覆盖率

GitLab CI 模板（assets/gitlab-ci-nodejs.yml）：

• 多阶段流水线
• 依赖项缓存
• 手动部署到生产环境
• 自动部署到预发布环境
• 报告代码覆盖率

使用模板的步骤：

1. 复制合适的模板文件
2. 将文件放在正确的位置：
   • GitHub Actions：.github/workflows/ci.yml
   • GitLab CI：.gitlab-ci.yml
3. 自定义部署目标、环境变量和分支名称
4. 在平台设置中添加所需的机密信息

4. 部署配置

Vercel 部署

对于 GitHub Actions：

- uses: amondnet/vercel-action@v25
  with:
    vercel-token: ${{ secrets.VERCEL_TOKEN }}
    vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
    vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
    vercel-args: '--prod'

所需机密信息：

• VERCEL_TOKEN：从 Vercel 账户设置中获取
• VERCEL_ORG_ID：从 Vercel 项目设置中获取
• VERCEL_PROJECT_ID：从 Vercel 项目设置中获取

Netlify 部署

- run: |
    npm install -g netlify-cli
    netlify deploy --prod --dir=.next
  env:
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

AWS S3 + CloudFront

- uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

- run: |
    aws s3 sync .next/static s3://${{ secrets.S3_BUCKET }}/static
    aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DIST_ID }} --paths "/*"

5. 测试集成

配置测试执行和相应的报告：

Jest 配置：

- name: Run tests with coverage
  run: npm test -- --coverage --coverageReporters=text --coverageReporters=lcov

- name: Upload coverage
  uses: codecov/codecov-action@v4
  with:
    files: ./coverage/lcov.info
    flags: unittests

快速失败策略：

# Run quick tests first
jobs:
  lint:  # Fails in ~30 seconds
  test:  # Fails in ~2 minutes
  build: # Fails in ~5 minutes
    needs: [lint, test]
  deploy:
    needs: [build]

6. 基于分支的工作流

针对不同分支实施不同的行为：

功能分支 / PR：

• 仅运行代码检查和测试
• 不部署
• 在 PR 评论中添加测试结果

Develop 分支：

• 运行代码检查、测试和构建
• 部署到预发布环境
• 自动部署

Main 分支：

• 运行代码检查、测试和构建
• 部署到生产环境
• 手动审批（可选）
• 创建发布标签

示例：

deploy_staging:
  if: github.ref == 'refs/heads/develop'
  # Deploy to staging

deploy_production:
  if: github.ref == 'refs/heads/main'
  environment: production  # Requires manual approval
  # Deploy to production

工作流决策树

按照此决策树生成合适的流水线：

1. 使用哪个平台？

   • GitHub → 使用 assets/github-actions-nodejs.yml
   • GitLab → 使用 assets/gitlab-ci-nodejs.yml
   • CircleCI/Jenkins → 改编 GitHub Actions 模板
   • 不确定 → 查阅 references/platform-comparison.md

2. 需要哪些阶段？

   • 始终包含：Lint、Test、Build
   • 可选：安全扫描、E2E 测试、性能测试
   • 如果从 CI 部署，则添加部署阶段

3. 使用哪个部署平台？

   • Vercel → 使用 Vercel 部署示例
   • Netlify → 使用 Netlify CLI 方案
   • AWS → 使用 AWS Actions/CLI
   • 自定义 → 实现自定义部署脚本

4. 使用哪些触发条件？

   • 推送到 main/develop 时
   • 创建拉取请求时
   • 创建标签时
   • 手动分发工作流时

5. 需要哪些环境变量？

   • 平台令牌（Vercel、Netlify、AWS）
   • 外部服务的 API 密钥
   • 构建时环境变量
   • 功能标志

最佳实践

安全性

• 将所有密钥存储在平台的密钥管理中（切勿写入代码）
• 使用最小权限令牌（尽可能设为只读）
• 定期轮换密钥
• 审核密钥访问权限
• 切勿记录密钥（使用 *** 遮蔽）

性能

• 尽可能充分地缓存依赖项
• 并行运行相互独立的作业
• 使用矩阵构建进行多版本测试
• 尽早失败：先运行快速检查，再运行耗时任务
• 优化 Docker 层缓存

可靠性

• 固定 Node.js 的确切版本（使用 18.x，而不只是 18）
• 提交锁文件（package-lock.json）
• 为不稳定的外部服务添加重试逻辑
• 设置合理的超时时间（最长 10-15 分钟）
• 对非关键步骤使用 continue-on-error

可维护性

• 添加注释，说明复杂逻辑
• 使用可复用工作流/模板
• 保持配置 DRY（不要重复自己）
• 对所有流水线变更进行版本控制
• 在 README 中记录所需密钥

常见模式

多环境部署

deploy_staging:
  environment: staging
  if: github.ref == 'refs/heads/develop'

deploy_production:
  environment: production
  if: github.ref == 'refs/heads/main'
  needs: [deploy_staging]

矩阵测试

strategy:
  matrix:
    node-version: [16.x, 18.x, 20.x]
    os: [ubuntu-latest, windows-latest]

条件步骤

- name: Deploy
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  run: npm run deploy

构件管理

- name: Upload build
  uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: .next/
    retention-days: 7

- name: Download build
  uses: actions/download-artifact@v4
  with:
    name: build-output

故障排除

流水线失败

1. 检查操作/作业日志中的错误消息
2. 确认已设置环境变量和密钥
3. 在添加到流水线之前，先在本地测试命令
4. 查阅文档，检查平台特有的问题

构建缓慢

1. 确认缓存正常工作（检查缓存命中/未命中日志）
2. 并行运行相互独立的作业
3. 如果有可用的更快运行器，请使用它们
4. 优化依赖项安装

部署失败

1. 确认部署令牌有效
2. 检查平台状态页面
3. 查看部署日志
4. 在本地测试部署命令

资源

模板（assets/）

• github-actions-nodejs.yml：完整的 GitHub Actions 工作流
• gitlab-ci-nodejs.yml：完整的 GitLab CI 流水线

参考文档（references/）

• platform-comparison.md：CI/CD 平台、部署目标、最佳实践和常见模式的详细对比

使用示例

用户请求：“创建一个 GitHub Actions 工作流，用于运行测试并部署到 Vercel”

步骤：

1. 复制 assets/github-actions-nodejs.yml 模板
2. 如果 .github/workflows/ 目录不存在，则创建该目录
3. 保存为 .github/workflows/ci.yml
4. 使用 Vercel 凭据更新部署部分
5. 在 GitHub 仓库设置中添加密钥：
   • VERCEL_TOKEN
   • VERCEL_ORG_ID
   • VERCEL_PROJECT_ID
6. 提交并推送以触发工作流

用户请求：“设置包含暂存和生产环境的 GitLab CI”

步骤：

1. 复制 assets/gitlab-ci-nodejs.yml 模板
2. 在仓库根目录将其保存为 .gitlab-ci.yml
3. 配置 GitLab CI/CD 变量：
   • VERCEL_TOKEN
   • 其他部署凭据
4. 检查生产环境的手动审批设置
5. 提交以触发流水线

高级配置

Monorepo 支持

paths:
  - 'apps/frontend/**'
  - 'packages/**'

定时运行

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

外部服务集成

- name: Notify Slack
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Security Scanning

- name: Run security audit
  run: npm audit --audit-level=moderate

- name: Check for vulnerabilities
  uses: snyk/actions/node@master
  env:
    SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}