generate-github-workflow

技能（Skill）：生成GitHub工作流程

目的 (Purpose)

为各种软件项目生成满足此技能的 附录 A：工作流输出合同 的 GitHub Actions 工作流文件。标准化结构、触发器和安全性可降低 CI/CD 设置成本并提高可维护性和可审核性，同时避免常见的安全和权限问题。该技能仅产生工作流YAML；它与文档或规则技能无关。如果用户稍后需要 README 或 AGENTS.md 更新，请单独调用这些技能。

---

核心目标（Core Objective）

首要目标：针对用户的场景、堆栈和安全态势生成完整、符合规范且可立即运行的 GitHub Actions 工作流 YAML 文件 — 只需要替换占位符即可部署。

成功标准（必须满足所有要求）：

1. ✅ 符合附录 A：输出满足附录 A 中的所有强制结构和安全需求（名称、工作、运行、步骤、固定操作、无硬编码秘密）
2. ✅ 窄触发器：on 块的范围仅限于特定分支/路径/标签 - 没有没有过滤器的裸露 on: Push
3. ✅ 最小权限：在工作流程或作业级别将“权限”设置为场景类型所需的最低权限（CI：“内容：读取”；发布：“内容：写入”、“包：写入”）
4. ✅ 堆栈对齐：Runner、语言版本、包管理器和命令与用户指定的堆栈匹配
5. ✅ 写入前用户确认：列出必需的注释和占位符，并在写入 .github/Workflows/ 之前获得用户确认

验收测试：用户替换占位符后，除了秘密名称和环境特定值之外，工作流是否可以在目标存储库中运行而无需进一步修改？

---

范围边界（范围边界）

本技能负责：

• 为 CI、PR 检查、发布和计划场景生成完整的 GitHub Actions 工作流 YAML
• 安全强化（固定操作、最小权限、无硬编码秘密）
• 堆栈对齐（Node/Python/Go/Rust 运行程序、包管理器、构建命令）
• 多工作流生成（CI + Release 分成单独的文件）
• 与现有工作流程的冲突检测
• Go + Docker + GHCR + GoReleaser 模式（参见附录 B）

本技能不负责：

• 链接到文档技能（README、AGENTS.md 更新）——在工作流生成后单独调用这些技能
• 无需用户确认即可写入 .github/工作流s/
• 在没有警告的情况下覆盖现有的工作流程
• 实现已在“.goreleaser.yaml”或 Dockerfile 中定义的构建/发布逻辑
• 生成非 GitHub CI/CD（GitLab CI、Jenkins 等）

转交点：生成并确认工作流YAML后，经用户批准将文件写入.github/工作流/。对于新工作流触发的文档更新，请单独使用文档技能。

---

使用场景（用例）

• 新项目设置：将 CI（构建、测试、lint）或 PR 检查工作流添加到新存储库。
• 统一标准：在多个存储库中协调工作流程风格和命名，以进行操作和审计。
• 填补空白：使用最少的权限和固定版本将缺少的 CI/发布/预定工作流添加到遗留项目中。
• 基于场景：为给定场景生成 YAML（例如“仅在 PR 上运行测试”、“在标签上构建和发布”）。

何时使用：当用户或项目需要“为当前或指定项目创建或添加 GitHub 工作流”时。

范围：此技能的输出遵循嵌入式附录 A（狭窄的触发器、最小权限、固定版本、可审核）。通用模板（例如 Skills.sh github-actions-templates）更加通用；这项技能强调安全性和可维护性。

---

行为（行为）

原则（原则）

• 附录A具有权威性：输出的YAML必须满足附录A（结构、命名、安全性、可维护性）。
• 窄触发器：on必须指定分支/路径/标签；避免每次推送时触发。常见模式：带有“branches”或“paths”的“push”/“pull_request”。 发布 工作流必须仅在版本标签上触发（例如push:tags:['v*']）并且存在于与 CI 不同的文件中。
• 最小权限：当工作流需要repo write、PR或Secrets时，将工作流或作业级别的“权限”设置为所需的最低权限；例如CI 内容：读取，释放内容：写入，包：写入；避免“全部”。
• 固定版本：固定第三方操作（提交 SHA 或主要版本标签）；不要使用“@master”或未固定的引用；更喜欢安全/扫描操作的特定版本（例如 Trivy）。

语气和风格

• 使用客观的技术语言；保持工作流程和步骤“名称”简短且便于操作日志阅读。
• 匹配项目堆栈：按项目类型（Node/Python/Go/Rust）和现有约定选择运行器、包管理器和构建命令；如果项目已经有工作流程，请调整命名和风格。

IN（输入）驱动

• 若存在 CLAUDE.md 或 .ai-cortex/config.yaml，优先读取其中的 test_command、base_branch 等；否则从用户输入或项目推断。参见 docs/guides/project-config.md。
• 使用用户的场景（例如“CI：在 PR 上运行测试”、“发布：在标签上构建和上传”）和 堆栈（语言、包管理器、测试/构建命令）来生成工作流；当信息丢失时使用合理的占位符并将其标记为替换；不要发明命令或路径。

交互（互动）

• 写入前确认：生成YAML后，列出必填注释（占位符、分支名称、用户必须设置的Secret名称），然后要求确认；不要写入 .github/工作流s/ 或在未经用户确认的情况下提交。
• 多个文件/发布：如果生成多个工作流（例如 CI + Release）或使用写入权限（contents: write、packages: write），列出要创建/覆盖的文件和权限范围，然后在写入之前确认。
• 冲突：如果目标路径已经存在目的相同或重叠的工作流，则警告并询问是否覆盖或保存到其他地方；不要默默地覆盖。

---

输入与输出 (Input & Output)

输入（输入）

• 场景：目的（CI、PR 检查、发布、计划、矩阵）。
• Stack：语言和版本（例如 Node 20、Python 3.11、Go 1.21）、包管理器（npm/pnpm/yarn、pip、cargo）、测试/构建/发布命令。
• 触发器：分支（例如main、develop）、路径过滤器、可选的工作流_dispatch。
• 目标路径：写入文件的位置，默认项目根目录下的.github/Workflows/；对于多个工作流，指定每个文件名（例如“ci.yml”、“release.yml”）。

输出（输出）

• 工作流 YAML：完整文件内容符合附录 A，准备写入 .github/工作流s/<name>.yml。
• 注释：列出占位符（例如“npm run test”、分支“main”）、秘密名称以及用户必须配置的任何项目。

---

限制（限制）

硬边界（Hard Boundaries）

• 不要违反附录A：输出必须有name、on、jobs，并且每个作业必须有runs-on和steps；不要使用未固定的第三方操作或硬编码的机密。
• 不要过度触发：除非用户明确请求，否则不要使用没有分支/路径过滤器的裸“on:push”。
• 不要发明命令：对未知的测试/构建/发布命令使用占位符并标记“替换为实际命令”；不要发明脚本或路径。
• 不要忽略现有的工作流：如果项目已经有.github/工作流/，请调整命名和风格并避免重复或冲突。
• 不要重复构建逻辑：如果项目使用 GoReleaser、Dockerfile 等进行构建和镜像塑造，则工作流程仅触发、登录并传递参数（例如 GITHUB_TOKEN、BUILDX_BUILDER）；不要重新实现该逻辑。

技能边界 (Skill Boundaries)

不要做这些（其他技能可以处理它们）：

• 不要链接到文档或自述文件技能 - 单独调用它们
• 未经用户确认，请勿写入 .github/工作流s/
• 不要默默地覆盖现有的工作流程
• 不要重新实现 .goreleaser.yaml 或 Dockerfiles 中已定义的构建/发布逻辑
• 不要为非 GitHub 平台（GitLab CI、Jenkins 等）生成 CI/CD

何时停止并交接：

• 编写工作流文件并确认后，如果需要 README/AGENTS.md 更新，请移交给文档技能
• 当用户需要注册表或机密配置时，提供指导但不自动进行外部服务设置

---

自检（Self-Check）

中核となる成功基準

• 付録 A に準拠：出力が付録 A の必須構造とセキュリティ要件をすべて満たしている（名前、ジョブ、実行環境、ステップ、固定アクション、ハードコードされたシークレットがない）
• 限定的なトリガー：onブロックの対象が特定のブランチ／パス／タグに限定されている — フィルターのない裸のon：pushは不可
• 最小権限：ワークフローまたはジョブレベルで「権限」を、シナリオの種類に必要な最低限に設定する
• スタックとの整合性：ランナー、言語のバージョン、パッケージマネージャー、コマンドがユーザー指定のスタックと一致している
• 書き込み前にユーザーの確認を得る：必要なコメントとプレースホルダーを列挙し、.github/Workflows/ に書き込む前にユーザーの確認を得る

ワークフロー品質チェック

• 付録 A：出力は付録 A の必須構造とセキュリティ要件を満たしていますか？
• トリガー：「on」は特定のブランチ／パス／タグに限定されていますか？
• 権限とセキュリティ：最小限の「権限」が設定されていますか？サードパーティのアクションは固定されていますか？ハードコードされたシークレットはありませんか？
• 実行可能性：ユーザーがプレースホルダーを置き換えた後、ワークフローは対象リポジトリで実行できますか？
• スタックとの整合性：ランナー、言語のバージョン、パッケージマネージャー、コマンドはユーザーのスタックと一致していますか？
• ステップの順序と依存関係：複数ステップのジョブ（例：QEMU → Buildx → ログイン → GoReleaser）では、順序は正しく、ids/env 変数は渡されていますか？Go + Docker + GoReleaser については 付録 B を参照してください。

受け入れテスト

ユーザーがプレースホルダーを置き換えた後、シークレット名と環境固有の値を除き、ワークフローは追加の変更なしで対象リポジトリ上で実行できますか？

---

例（サンプル）

例 1：Node CI（PR でのテスト＋lint）

入力：シナリオ：CI。スタック：Node 20、pnpm、テスト pnpm test、lint pnpm lint。トリガー：「main」への「pull_request」。ファイル：ci.yml。

期待される結果：「CI」などの「name」を持つ単一の「ci.yml」； on: pull_request: branches: [main]; ubuntu-latest 上で実行するジョブ。チェックアウト、Node/pnpm のセットアップ、インストール、lint、テストを含む；固定された公式の「actions/checkout」と「pnpm/action-setup」（または同等のもの）を使用；ハードコードされたシークレットなし；「permissions」を設定する場合は読み取り専用。

例 2：パスフィルターを使った PR チェック

入力：シナリオ：PR チェック。スタック：Go 1.21、テスト「go test ./...」。go.mod または *.go に変更があった場合のみ実行。ファイル：pr-check.yml。

期待される結果：on.pull_request と paths: ['**.go', 'go.mod']；固定された「actions/setup-go」を使うジョブ。チェックアウト、Go のセットアップ、テストを行うステップ；書き込みが不要なら「permissions」を省略するか、「contents: read」を設定する。

例 3：Go リリース（Docker + GHCR + GoReleaser）

入力：シナリオ：CD／リリース。スタック：Go、Docker マルチアーキテクチャ（amd64/arm64）、イメージと GitHub Release 用の GoReleaser。トリガー：「v*」タグへの「push」のみ。ファイル：release.yml。

期待される結果：on:push:tags:['v*']; permissionsにcontents: write、packages: writeを含める。ステップ：チェックアウト（fetch-深度：0）→ Go のセットアップ（go-version-file：go.mod、キャッシュ）→ QEMU のセットアップ（linux/amd64、linux/arm64）→ Docker Buildx のセットアップ（id：buildx、同じプラットフォーム）→ GHCR へのログイン（docker/login-action、ghcr.io）→ GoReleaser（goreleaser/goreleaser-action を固定し、GITHUB_TOKEN と BUILDX_BUILDER: ${{ steps.buildx.outputs.name }} を渡す）。.goreleaser.yaml／Dockerfile で定義されているロジックを再実装しないでください。 付録 B を参照。

例 4（エッジケース）：情報が最小限の場合

入力：プロジェクト：legacy-api。説明なし。言語とコマンドは不明。ユーザーは「最低限の CI プレースホルダーワークフロー」を希望。

期待される結果：付録 A に準拠した、構造が完全な YAML を生成する；ランナーとステップにはプレースホルダー（例：「ランナーとインストール／テストコマンドを指定」）を使い、「置き換える必要あり」と明記する；「on」の対象を限定する（例：「pull_request:branches:[main]」）；テストやビルドコマンドを作り出さない；ユーザーが後で記入できるよう、「name」、「on」、「jobs」、「runs-on」、「steps」と推奨フィールド（例：「permissions」）を残す。

---