Back to Details

github-actions-ci-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Actions CI Workflow

GitHub Actions CI工作流

Set up complete GitHub Actions workflows for continuous integration and deployment of worldbuilding applications.
为Web应用搭建完整的GitHub Actions持续集成与部署工作流。

Overview

概述

To configure comprehensive CI/CD pipelines with GitHub Actions:
  1. Analyze the project structure and dependencies
  2. Generate workflow files for lint, test, build, and deploy stages
  3. Configure caching strategies for node_modules, Next.js cache, and build artifacts
  4. Add preview deployment with automatic URL comments on pull requests
  5. Set up environment-specific deployment targets
要使用GitHub Actions配置全面的CI/CD流水线，请遵循以下步骤：
  1. 分析项目结构与依赖
  2. 生成用于代码检查、测试、构建与部署阶段的工作流文件
  3. 配置node_modules、Next.js缓存及构建产物的缓存策略
  4. 添加预览部署功能，并在拉取请求中自动添加URL评论
  5. 设置环境专属的部署目标

Workflow Structure

工作流结构

Create the following workflow files in 
.github/workflows/
:
在
.github/workflows/
目录下创建以下工作流文件：

CI Workflow (
ci.yml
)

CI工作流（
ci.yml
）

To set up continuous integration:
  1. Configure triggers for push to main/master and pull requests
  2. Set up job matrix for multiple Node.js versions if needed
  3. Add checkout, dependency installation with caching
  4. Run linting (ESLint, Prettier, type checking)
  5. Execute test suites with coverage reporting
  6. Build the application to verify no build errors
  7. Upload build artifacts for deployment jobs
要搭建持续集成：
  1. 配置推送至main/master分支及拉取请求的触发规则
  2. 若需要，为多版本Node.js设置任务矩阵
  3. 添加代码拉取、带缓存的依赖安装步骤
  4. 运行代码检查（ESLint、Prettier、类型检查）
  5. 执行测试套件并生成覆盖率报告
  6. 构建应用以验证无构建错误
  7. 上传构建产物供部署任务使用

Deploy Workflow (
deploy.yml
)

部署工作流（
deploy.yml
）

To set up continuous deployment:
  1. Trigger on push to main/master branch
  2. Download build artifacts from CI workflow
  3. Deploy to target environment (Vercel, Netlify, AWS, etc.)
  4. Set environment variables and secrets
  5. Notify on deployment success/failure
要搭建持续部署：
  1. 设置触发规则为推送至main/master分支
  2. 从CI工作流中下载构建产物
  3. 部署至目标环境（Vercel、Netlify、AWS等）
  4. 配置环境变量与密钥
  5. 发送部署成功/失败通知

Preview Deployment (
preview.yml
)

预览部署（
preview.yml
）

To set up preview deployments for pull requests:
  1. Trigger on pull_request events
  2. Build and deploy to preview environment
  3. Generate unique preview URL
  4. Comment preview URL on pull request using GitHub API
  5. Clean up preview deployments when PR is closed
要为拉取请求设置预览部署：
  1. 设置触发规则为pull_request事件
  2. 构建并部署至预览环境
  3. 生成唯一的预览URL
  4. 使用GitHub API在拉取请求中评论预览URL
  5. 当PR关闭时清理预览部署资源

Caching Strategy

缓存策略

To optimize workflow performance:
  1. Cache 
    node_modules
    with dependency lock file as cache key
  2. Cache Next.js build cache (
    .next/cache
    ) for faster builds
  3. Cache testing artifacts and coverage reports
  4. Use 
    actions/cache@v3
    with appropriate cache keys
  5. Implement cache restoration fallbacks for partial matches
要优化工作流性能：
  1. 以依赖锁文件为缓存键，缓存
    node_modules
  2. 缓存Next.js构建缓存（
    .next/cache
    ）以加快构建速度
  3. 缓存测试产物与覆盖率报告
  4. 使用
    actions/cache@v3
    并配置合适的缓存键
  5. 为部分匹配的缓存实现回退恢复逻辑

Resources

资源

Consult 
references/github-actions-best-practices.md
for workflow optimization patterns and security best practices.
Use 
scripts/generate_ci_workflow.py
to scaffold workflow files based on detected project configuration.
Reference 
assets/workflow-templates/
for starter templates for common frameworks (Next.js, React, Node.js).
参考
references/github-actions-best-practices.md
获取工作流优化模式与安全最佳实践。
使用
scripts/generate_ci_workflow.py
根据检测到的项目配置生成工作流文件模板。
参考
assets/workflow-templates/
获取常见框架（Next.js、React、Node.js）的入门模板。

Implementation Steps

实施步骤

To implement complete CI/CD with GitHub Actions:
  1. Detect Project Configuration
    • Identify framework (Next.js, Vite, CRA, etc.)
    • Detect package manager (npm, yarn, pnpm)
    • Find test runner (Jest, Vitest, Playwright)
    • Check for linting configuration
  2. Generate Workflow Files
    • Use 
      scripts/generate_ci_workflow.py
      with detected configuration
    • Customize jobs based on project requirements
    • Add matrix builds if testing multiple environments
  3. Configure Secrets and Variables
    • Document required secrets in README or workflow comments
    • Set up environment-specific variables
    • Configure deployment credentials
  4. Add Preview Deployments
    • Generate preview workflow with URL commenting
    • Configure preview environment provider
    • Set up cleanup automation
  5. Optimize Caching
    • Implement multi-level caching strategy
    • Use cache keys based on lock files
    • Add cache restoration logic
  6. Test and Validate
    • Push workflows to repository
    • Create test PR to verify preview deployments
    • Check workflow execution times and optimize
要使用GitHub Actions搭建完整的CI/CD：
  1. 检测项目配置
    • 识别框架（Next.js、Vite、CRA等）
    • 检测包管理器（npm、yarn、pnpm）
    • 确定测试运行器（Jest、Vitest、Playwright）
    • 检查代码检查配置
  2. 生成工作流文件
    • 结合检测到的配置，使用
      scripts/generate_ci_workflow.py
    • 根据项目需求自定义任务
    • 若需测试多环境，添加矩阵构建
  3. 配置密钥与变量
    • 在README或工作流注释中记录所需密钥
    • 设置环境专属变量
    • 配置部署凭证
  4. 添加预览部署
    • 生成带URL评论功能的预览工作流
    • 配置预览环境提供商
    • 设置清理自动化
  5. 优化缓存
    • 实现多级缓存策略
    • 使用基于锁文件的缓存键
    • 添加缓存恢复逻辑
  6. 测试与验证
    • 将工作流推送至仓库
    • 创建测试PR以验证预览部署
    • 检查工作流执行时间并优化

Advanced Features

高级功能

To add advanced CI/CD capabilities:
  • Parallel Jobs: Split test suites across multiple jobs for faster execution
  • Conditional Deployments: Deploy only specific paths or when conditions are met
  • Status Checks: Require CI passing before merge
  • Deployment Gates: Add manual approval steps for production deployments
  • Performance Monitoring: Integrate Lighthouse CI or bundle analysis
  • Dependency Updates: Automate dependency updates with Dependabot integration
要添加高级CI/CD能力：
  • 并行任务：将测试套件拆分至多个任务以加快执行速度
  • 条件部署：仅在特定路径或满足条件时执行部署
  • 状态检查：要求CI通过后才能合并
  • 部署闸门：为生产部署添加手动审批步骤
  • 性能监控：集成Lighthouse CI或包体积分析
  • 依赖更新：通过Dependabot集成实现依赖自动更新

Framework-Specific Configuration

框架专属配置

Next.js Applications

Next.js应用

To optimize for Next.js:
  1. Cache 
    .next/cache
    directory for faster builds
  2. Set 
    NEXT_TELEMETRY_DISABLED=1
    to disable telemetry
  3. Use 
    next build
    and 
    next export
    for static exports
  4. Configure ISR revalidation for preview deployments
针对Next.js优化：
  1. 缓存
    .next/cache
    目录以加快构建速度
  2. 设置
    NEXT_TELEMETRY_DISABLED=1
    以禁用遥测
  3. 使用
    next build
    与
    next export
    生成静态导出文件
  4. 为预览部署配置ISR重新验证

Full-Stack Applications

全栈应用

To handle full-stack deployments:
  1. Set up separate jobs for frontend and backend
  2. Configure database migrations in deployment workflow
  3. Run integration tests against preview environment
  4. Coordinate deployment order (backend first, then frontend)
处理全栈部署：
  1. 为前端与后端设置独立任务
  2. 在部署工作流中配置数据库迁移
  3. 针对预览环境运行集成测试
  4. 协调部署顺序（先部署后端，再部署前端）

Deployment Providers

部署提供商

Consult 
references/deployment-providers.md
for platform-specific configuration:
  • Vercel: Use vercel-action with project configuration
  • Netlify: Use netlify-cli with site ID and auth token
  • AWS: Configure S3/CloudFront or ECS deployment
  • Docker: Build and push container images to registry
  • Self-Hosted: SSH deployment with rsync or git pull
参考
references/deployment-providers.md
获取平台专属配置：
  • Vercel：使用vercel-action并配置项目信息
  • Netlify：使用netlify-cli并提供站点ID与认证令牌
  • AWS：配置S3/CloudFront或ECS部署
  • Docker：构建并推送容器镜像至镜像仓库
  • 自托管：通过SSH使用rsync或git pull进行部署

Monitoring and Notifications

监控与通知

To add monitoring and notifications:
  1. Configure Slack/Discord webhooks for deployment notifications
  2. Add GitHub status checks for required CI jobs
  3. Set up error tracking integration (Sentry, etc.)
  4. Monitor workflow execution times and optimize slow jobs
  5. Track deployment frequency and failure rates
添加监控与通知：
  1. 配置Slack/Discord webhook以接收部署通知
  2. 为必要的CI任务添加GitHub状态检查
  3. 集成错误追踪工具（如Sentry等）
  4. 监控工作流执行时间并优化慢任务
  5. 追踪部署频率与失败率

Troubleshooting

故障排除

Common issues and solutions:
  • Cache Misses: Verify cache key includes all dependency files
  • Timeout Errors: Increase timeout or split into parallel jobs
  • Permission Errors: Check repository secrets and permissions
  • Build Failures: Ensure environment variables are set correctly
  • Preview URL Not Commented: Verify PR comment permissions and token scope
常见问题与解决方案：
  • 缓存未命中：验证缓存键是否包含所有依赖文件
  • 超时错误：增加超时时间或拆分为并行任务
  • 权限错误：检查仓库密钥与权限
  • 构建失败：确保环境变量设置正确
  • 预览URL未评论：验证PR评论权限与令牌范围