CI/CD流水线生成器Skill cicd-pipeline-generator

name: cicd-pipeline-generator description: 此技能应用于创建或配置用于自动化测试、构建和部署的CI/CD流水线文件。适用于生成GitHub Actions工作流、GitLab CI配置、CircleCI配置或其他CI/CD平台配置。特别适合为Node.js/Next.js应用程序设置自动化流水线，包括代码检查、测试、构建以及部署到Vercel、Netlify或AWS等平台。

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. 流水线配置生成

遵循以下原则生成流水线配置：

流水线阶段

使用这些标准阶段构建流水线：

安装依赖
- 从仓库检出代码
- 设置运行时环境（Node.js版本）
- 恢复缓存的依赖项
- 使用 npm ci 安装依赖项
- 为后续运行缓存依赖项
代码检查
- 运行ESLint进行代码质量检查
- 运行TypeScript类型检查
- 在代码检查错误时快速失败
测试
- 执行单元测试
- 执行集成测试
- 生成代码覆盖率报告
- 将覆盖率上传到报告服务（Codecov、Coveralls）
构建
- 创建生产构建
- 验证构建成功
- 存储构建产物
部署
- 部署到预发布环境（develop分支）
- 部署到生产环境（main分支）
- 运行部署后冒烟测试

缓存策略

实施有效的缓存以加速构建：

# 基于 package-lock.json 缓存 node_modules
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):

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

使用模板步骤：

复制相应的模板文件
放置在正确的位置：
- GitHub Actions: .github/workflows/ci.yml
- GitLab CI: .gitlab-ci.yml
自定义部署目标、环境变量和分支名称
将所需密钥添加到平台设置中

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: npm test -- --coverage --coverageReporters=text --coverageReporters=lcov

- name: 上传覆盖率
  uses: codecov/codecov-action@v4
  with:
    files: ./coverage/lcov.info
    flags: unittests

快速失败策略：

# 先运行快速测试
jobs:
  lint:  # 约30秒内失败
  test:  # 约2分钟内失败
  build: # 约5分钟内失败
    needs: [lint, test]
  deploy:
    needs: [build]

6. 基于分支的工作流

实现不同分支的不同行为：

功能分支 / PR：

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

开发分支：

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

主分支：

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

示例：

deploy_staging:
  if: github.ref == 'refs/heads/develop'
  # 部署到预发布环境

deploy_production:
  if: github.ref == 'refs/heads/main'
  environment: production  # 需要手动批准
  # 部署到生产环境

工作流决策树

遵循此决策树生成合适的流水线：

选择哪个平台？
- GitHub → 使用 assets/github-actions-nodejs.yml
- GitLab → 使用 assets/gitlab-ci-nodejs.yml
- CircleCI/Jenkins → 适配GitHub Actions模板
- 不确定 → 参考 references/platform-comparison.md
需要哪些阶段？
- 始终包含：代码检查、测试、构建
- 可选：安全扫描、端到端测试、性能测试
- 如果从CI部署，则添加部署阶段
选择哪个部署平台？
- Vercel → 使用Vercel部署示例
- Netlify → 使用Netlify CLI方法
- AWS → 使用AWS Actions/CLI
- 自定义 → 实现自定义部署脚本
触发条件是什么？
- 推送到main/develop时
- 拉取请求时
- 创建标签时
- 手动触发工作流
需要哪些环境变量？
- 平台令牌（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: 部署
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  run: npm run deploy

产物管理

- name: 上传构建产物
  uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: .next/
    retention-days: 7

- name: 下载构建产物
  uses: actions/download-artifact@v4
  with:
    name: build-output

故障排除

流水线失败

检查操作/作业日志中的错误信息
验证环境变量和密钥是否已设置
在添加到流水线之前本地测试命令
在文档中检查平台特定问题

构建缓慢

验证缓存是否正常工作（检查缓存命中/未命中日志）
并行化独立作业
如果可用，使用更快的运行器
优化依赖项安装

部署失败

验证部署令牌是否有效
检查平台状态页面
查看部署日志
本地测试部署命令

资源

模板 (`assets/`)

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

参考文档 (`references/`)

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

使用示例

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

步骤：

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

用户请求：“设置具有预发布和生产环境的GitLab CI”

步骤：

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

高级配置

单体仓库支持

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

定时运行

on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨2点

外部服务集成

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

安全扫描

- name: 运行安全审计
  run: npm audit --audit-level=moderate

- name: 检查漏洞
  uses: snyk/actions/node@master
  env:
    SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}