github-actions-workflows

GitHub Actions 工作流

提供专家指导，帮助设计可靠、安全且高性能的 GitHub Actions CI/CD 管道，涵盖矩阵构建、可复用工作流、缓存和部署自动化模式。

适用场景

• 从头开始使用 GitHub Actions 搭建 CI/CD 管道
• 优化缓慢或成本高昂的 GitHub Actions 工作流
• 实施矩阵构建，进行多环境测试
• 创建可复用工作流和复合操作，构建 DRY 管道
• 在各环境中安全管理机密
• 配置缓存，以便重复使用依赖项和构建产物
• 设置带有预发布和生产环境关卡的部署工作流
• 调试失败或不稳定的工作流运行
• 实施并发控制，防止重复运行

快速参考

任务	加载参考文档
矩阵构建、可复用工作流、缓存、部署、并发控制	skills/github-actions-workflows/references/workflow-patterns.md

核心原则

• 结构化作业：将工作流拆分为清晰、独立且依赖关系明确的作业
• DRY 配置：使用可复用工作流和复合操作，避免重复
• 安全第一：使用 GitHub Secrets、OIDC 和最低必要权限
• 积极缓存：缓存依赖项、构建输出和测试夹具
• 谨慎设置触发条件：配置事件触发条件，避免不必要的工作流运行
• 为工作流编写文档：添加注释，解释不易理解的 YAML 配置

工作流

1. 设计

编写 YAML 之前，先规划管道结构。

• 确定触发事件（push、pull_request、schedule、workflow_dispatch）
• 梳理作业依赖关系以及可并行运行的作业
• 确定缓存机会（依赖项、构建输出）
• 规划环境晋级流程（开发、预发布、生产）

2. 实施

逐步构建管道。

• 从最简工作流开始，再逐步增加复杂度
• 使用矩阵构建进行多环境测试
• 提取可复用工作流，用于共享模式
• 使用环境保护机制配置机密管理

3. 优化

缩短运行时间并降低成本。

• 分析工作流运行时间，找出瓶颈
• 为依赖项和构建产物添加缓存
• 使用并发控制取消冗余运行
• 配置路径筛选器，跳过不受影响的工作流

4. 维护

持续保持工作流健康运行。

• 将操作版本固定到特定 SHA，以确保安全
• 定期检查并更新操作
• 监控工作流运行时间趋势和成本
• 合并前对工作流变更进行同行评审

常见错误

• 使用 actions/checkout@main，而不是固定到 SHA 或版本标签
• 未设置 permissions 块（默认权限过于宽泛，包含读写权限）
• 缓存 node_modules，而不是包管理器的缓存目录
• 缺少 concurrency 组，导致重复部署
• 在工作流文件中硬编码机密，而不是使用 GitHub Secrets
• 每次推送都运行完整测试套件，而不是使用路径筛选器
• 未使用 workflow_call 在多个仓库间共享 CI 逻辑