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）
构建
- 创建生产构建
- 验证构建成功
- 存储构建产物
部署
- 部署到预发布环境（开发分支）
- 部署到生产环境（主分支）
- 运行部署后冒烟测试

缓存策略

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

# 基于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
- 自定义 → 实现自定义部署脚本
什么触发器？
- 推送到主分支/开发分支时
- 拉取请求时
- 创建标签时
- 手动工作流调度
需要哪些环境变量？
- 平台令牌（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 }}