github-actions-generator

GitHub Actions 生成器

根据当前最佳实践、安全标准和命名约定，生成可用于生产环境的 GitHub Actions 工作流和自定义操作。所有生成的资源都会自动使用 devops-skills:github-actions-validator 技能进行验证。

快速参考

功能	适用场景	参考资料
工作流	CI/CD、自动化、测试	references/best-practices.md
复合操作	可复用的步骤组合	references/custom-actions.md
Docker 操作	自定义环境/工具	references/custom-actions.md
JavaScript 操作	API 交互、复杂逻辑	references/custom-actions.md
可复用工作流	跨仓库共享模式	references/advanced-triggers.md
安全扫描	依赖审查、SBOM	references/best-practices.md
现代功能	摘要、环境	references/modern-features.md

---

触发器决策树

在读取参考资料或生成文件之前，先按照此决策树处理每个请求：

1. 如果用户请求 .github/workflows/*.yml CI/CD 自动化，选择工作流生成。
2. 如果用户请求 action.yml 或可复用步骤包，选择自定义操作生成。
3. 如果用户请求 workflow_call 或跨仓库共享流水线，选择可复用工作流生成。
4. 如果请求仅涉及安全扫描（依赖审查、SBOM、CodeQL），使用安全模式选择工作流生成。
5. 如果意图不明确，提出一个澄清问题：“你需要工作流、自定义操作，还是可复用工作流？”

渐进式披露路径

仅加载所选路径所需的内容，并按以下顺序进行：

路径	首先加载（必需）	接下来加载（仅在需要时）	主要模板
工作流生成	references/best-practices.md	references/common-actions.md、references/expressions-and-contexts.md、references/modern-features.md	assets/templates/workflow/basic_workflow.yml
自定义操作生成	references/custom-actions.md	references/best-practices.md	assets/templates/action/composite/action.yml、assets/templates/action/docker/、assets/templates/action/javascript/
可复用工作流生成	references/advanced-triggers.md	references/best-practices.md、references/common-actions.md	assets/templates/workflow/reusable_workflow.yml

如果所需的参考资料/模板不可用，请使用最接近的可用资料继续，并在输出中明确说明采用了替代项。

---

核心功能

1. 生成工作流

触发语：“创建一个用于……的工作流”、“构建 CI/CD 流水线……”

流程：

1. 了解需求（触发器、运行器、依赖项）
2. 界定信任边界（内部分支与 fork PR、外部触发器）
3. 将默认 permissions 设为只读，然后仅在必需时按作业提升权限
4. 参考 references/best-practices.md 中的模式
5. 参考 references/common-actions.md 中的操作版本
6. 生成工作流，包含：
   • 语义明确的名称、固定到 SHA 的操作、明确的权限
   • 并发控制、缓存、矩阵策略
   • 对 fork PR 安全的处理方式（不在不受信任的上下文中使用机密）
7. 使用 devops-skills:github-actions-validator 技能进行验证
8. 修复问题，并在需要时重新验证

最简示例：

name: CI Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm test

不受信任的 PR 防护措施（使用机密的作业必需）：

jobs:
  deploy:
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository

2. 生成自定义操作

触发条件：“创建复合操作……”“构建 Docker 操作……”“创建 JavaScript 操作……”

类型：

• **复合操作：**组合多个步骤 → 快速启动
• **Docker：**自定义环境／工具 → 隔离运行
• **JavaScript：**API 访问、复杂逻辑 → 启动最快

流程：

1. 使用 assets/templates/action/ 中的模板
2. 遵循 references/custom-actions.md 中的结构
3. 包含品牌信息、输入／输出和文档
4. 使用 devops-skills:github-actions-validator 技能进行验证

参见 references/custom-actions.md，了解：

• 操作元数据和品牌信息
• 目录结构模式
• 版本控制和发布工作流

3. 生成可复用工作流

触发条件：“创建可复用工作流……”“让此工作流可被调用……”

关键要素：

• 使用带有类型化输入的 workflow_call 触发器
• 显式声明机密（避免使用 secrets: inherit）
• 明确可信调用方的预期（记录组织／仓库边界）
• 从作业输出映射工作流输出
• 最小化权限

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy-token:
        required: false
    outputs:
      result:
        value: ${{ jobs.build.outputs.result }}

需要机密时，只传递所需的确切机密名称，并优先使用环境保护规则来管理部署阶段。

参见 references/advanced-triggers.md，了解完整模式。

4. 生成安全工作流

触发条件：“添加安全扫描……”“添加依赖项审查……”“生成 SBOM……”

组件：

• 依赖项审查：actions/dependency-review-action@v4
• SBOM 证明：actions/attest-sbom@v2
• CodeQL 分析：github/codeql-action

权限模型： 使用只读的工作流级基线，然后仅在需要写入作用域的安全作业中提升权限。

permissions:
  contents: read

jobs:
  security-scan:
    permissions:
      contents: read
      security-events: write  # For CodeQL
      id-token: write         # For attestations
      attestations: write     # For attestations

参见 references/best-practices.md 中有关安全的部分。

5. 现代功能

触发条件：“添加作业摘要……”“使用环境……”“在容器中运行……”

参见 references/modern-features.md，了解：

• 作业摘要（$GITHUB_STEP_SUMMARY）
• 带审批的部署环境
• 带服务的容器作业
• 工作流注释

6. 第三方操作文档和引用

使用第三方操作时（任何不在同一仓库中的 uses: 条目）：

1. 搜索文档：

   "[owner/repo] [version] github action documentation"
   

2. 或使用 Context7 MCP：

   • 使用 mcp__context7__resolve-library-id 查找操作
   • 使用 mcp__context7__query-docs 查找文档

3. 固定到 SHA，并附上版本注释：

   - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
   

4. 在回复中引用来源和版本：

   • 操作来源（仓库 URL）
   • 版本来源（发布／标签／变更日志 URL）
   • 选定的提交 SHA 和易读版本号
   • 所用来源的访问日期

参见 references/common-actions.md，了解预先验证过的操作版本。

---

验证工作流

**重要：**每个生成的资源都必须经过验证。

1. 生成工作流／操作文件
2. 调用 devops-skills:github-actions-validator 技能
3. 如果有错误：修复后重新验证
4. 如果成功：附上使用说明

仅在以下情况下跳过验证：

• 部分代码片段
• 文档示例
• 用户明确要求跳过

回退行为（工具和环境限制）

如果所需工具或网络访问不可用，请按以下确定顺序回退：

1. 如果 devops-skills:github-actions-validator 不可用，请运行本地回退检查：
   • actionlint（如果已安装）
   • yamllint（如果已安装）
   • 手动检查 YAML／架构，并明确注明“未经工具验证”
2. 如果 Context7 或互联网访问不可用：
   • 使用 references/common-actions.md 中已知的操作版本
   • 说明无法完成外部版本验证
3. 如果模板路径不存在：
   • 使用 assets/templates/ 中最接近的模板模式生成
   • 记录替代使用的模板

最终输出必须始终报告回退用法。

---

强制标准

所有生成的资源都必须遵循：

标准	实施方式
安全性	固定到 SHA，使用最小权限，屏蔽机密信息
性能	缓存、并发、浅克隆
命名	使用描述性名称，文件名采用小写字母和连字符
错误处理	设置超时，使用 if: always() 清理

完整指南请参阅 references/best-practices.md。

---

资源

参考文档

文档	内容	适用场景
references/best-practices.md	安全性、性能、模式	每个工作流
references/common-actions.md	Action 版本、输入、输出	使用公共 Action
references/expressions-and-contexts.md	${{ }} 语法、上下文、函数	复杂条件判断
references/advanced-triggers.md	workflow_run、dispatch、ChatOps	工作流编排
references/custom-actions.md	元数据、结构、版本控制	创建自定义 Action
references/modern-features.md	摘要、环境、容器	增强型工作流

模板

模板	位置
基本工作流	assets/templates/workflow/basic_workflow.yml
可复用工作流	assets/templates/workflow/reusable_workflow.yml
组合式 Action	assets/templates/action/composite/action.yml
Docker Action	assets/templates/action/docker/
JavaScript Action	assets/templates/action/javascript/

---

常见模式

矩阵测试

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20, 22]
  fail-fast: false

条件部署

deploy:
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'

工件共享

# Upload
- uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
  with:
    name: build-${{ github.sha }}
    path: dist/

# Download (in dependent job)
- uses: actions/download-artifact@c850b930e6ba138125429b7e5c93fc707a7f8427 # v4.1.4
  with:
    name: build-${{ github.sha }}

第三方 Action 引用区块

Third-party action citations:
- actions/checkout: https://github.com/actions/checkout (version: v6.0.2, sha: de0fac2e4500dabe0009e67214ff5f5447ce83dd, accessed: 2026-02-28)

---

完成标准

只有通过以下所有检查，任务才算完成：

1. 使用触发器决策树选择了请求路由。
2. 首先仅加载了所需的最少参考资料和模板。
3. 每个第三方 Action 都固定到提交 SHA，并注明来源/版本。
4. 已运行验证，或明确记录了跳过验证的例外情况/回退路径。
5. 输出包含假设、安全敏感决策（权限/机密信息）和生成的文件路径。

---

工作流摘要

1. 使用触发器决策树路由请求
2. 加载该路由所需的最少参考资料/模板
3. 按照强制安全和命名标准生成
4. 引用并固定第三方 Action（来源、版本、SHA）
5. 使用 devops-skills:github-actions-validator 验证（或记录回退方案）
6. 修复并重新验证，直到检查通过
7. 呈现通过验证的输出，并附上引用、假设和文件路径