设置

首次启用时，请先阅读 setup.md，以对齐自动激活规则、仓库结构（repo shape）及变更边界（mutation boundaries），再编辑工作流或触发运行。

适用场景

当用户需要设计、调试、加固 GitHub Actions 工作流，或编排发布流程、规划 runner 策略、调优 matrix、修复缓存问题、构建可复用工作流架构时，请使用本技能。

仅在结果依赖 GitHub Actions 语义与 GitHub 发布控制能力（而非通用 CI 建议）时使用本技能。

架构

记忆数据存储于 ~/github-actions/ 目录下。基础结构请参见 memory-template.md。

~/github-actions/
|-- memory.md              # 持久化仓库上下文与激活边界
|-- repo-map.md            # 仓库列表、分支、包管理器及部署目标
|-- workflow-defaults.md   # 触发器、权限、缓存与 runner 的稳定默认配置
|-- incidents.md           # 故障特征、根本原因及修复方案
`-- release-rules.md       # 发布准入门禁、审批要求与回滚说明

快速参考

仅加载当前工作流问题所需文件。

前提要求

• 可选但高价值工具：gh、jq、act
• 若用户需实时查看运行日志或修改工作流，则需具备 GitHub 仓库访问权限
• 部署凭据仅可通过 GitHub 托管的 secrets、environments 或 OIDC 获取

切勿要求用户提供个人访问令牌（PAT）、云平台密钥或私有签名材料等敏感信息。

CI/CD 示例

本技能中的 YAML 片段均为仓库工作流文件的示例。

诸如 ${{ github.* }}、${{ inputs.* }}、${{ vars.* }} 和 ${{ secrets.* }} 等引用属于 GitHub Actions 运行时环境，而非 agent 运行时环境。

agent 应围绕这些占位符进行设计，但不应期望直接读取其实际值。

覆盖范围

本技能将 GitHub Actions 视为交付操作系统（delivery OS），覆盖以下方面：

• 支持 push、pull_request、workflow_dispatch、schedule 和 workflow_call 等各类触发器的工作流编写
• 涵盖权限、并发控制、matrix、产物（artifacts）、缓存、服务（services）与 environments 的 job 设计
• 支持带受保护分支、审批机制、标签管理和回滚检查点的发布与部署流水线
• 面向不稳定运行（flaky runs）、缺失产物、缓存损坏及环境漂移等典型故障的应急响应

数据存储

~/github-actions/ 下的本地笔记可能包含：

• 仓库拓扑结构、受保护分支与 environment 名称
• 已验证可用的工作流默认配置及可复用工作流契约
• 高频故障特征、对应修复方法与预防建议
• 发布门禁、升级步骤与回滚约束条件

核心规则

1. 从触发器、目标与产物契约出发

编辑 YAML 前，须明确定义：

• 应触发工作流的事件
• 该工作流可影响的分支、标签或 environment
• 每个 job 必须产出的产物或状态

缺乏该契约，工作流易退化为职责不清的步骤集合，导致发布行为不可预测。

2. 默认采用显式权限声明与最小爆炸半径

在 workflow 或 job 级别声明 permissions:，且仅授予该 job 实际所需的最小权限。

将 contents: write、packages: write 与 id-token: write 视为例外情形，须提供明确理由。

3. 分离验证、构建、发布与部署关注点

将 pull request 验证、产物生成、发布分发与生产部署作为相互独立的责任单元。

优先使用 workflow_call 或轻量级可复用 job，避免构建一个承担全部功能的巨型工作流。

4. 为每次运行设定并发控制、超时与事件过滤

使用 concurrency 实现按分支或 environment 的运行取消；添加 timeout-minutes；通过分支或路径规则过滤噪声事件。

若未加约束，冗余运行将迅速耗尽分钟配额。

5. 优化确定性任务，而非随机副作用

以 lockfile 或显式版本号为键，缓存包管理器状态、工具链及稳定的构建输出。

使用 artifacts 实现 job 间的数据传递；禁止缓存依赖密钥、时间戳或可变部署状态的路径。

6. 基于日志与可复现证据进行调试

重写工作流前，先对故障进行分类：

• 触发器与条件不匹配
• 缺失依赖项或工具链漂移
• 凭据或权限被拒绝
• 产物或路径契约被破坏
• 外部依赖不稳定

应修复真实存在的故障模式，而非仅处理“熟悉”的表象。

7. 优先采用短期有效凭据与受保护部署面

尽可能使用 GitHub environments、审批门禁（reviewer gates）与 OIDC 联邦认证。

避免长期有效的云平台密钥、未经审查的 workflow_dispatch 部署，以及由不受信任事件触发的生产环境写入操作。

GitHub Actions 常见陷阱

• 在一个未设防护的工作流中混合 pull request 验证与生产部署 → 因错误事件导致意外发布。
• 为每个 job 授予宽泛权限 → 单个 action 或 step 被攻破时，影响范围过大。
• 使用无 lockfile 或版本标识的缓存 → 导致依赖陈旧、故障不可复现且难以排查。
• 放任 matrix 无成本控制地膨胀 → 消耗大量分钟配额，且噪音失败掩盖真正问题。
• 依赖未锁定版本的 ubuntu-latest 行为 → runner 镜像更新后突发工具链漂移。
• 重新构建而非提升（promote）已验证产物 → 导致发布的代码与经验证的代码不一致。
• 将重试（rerun）当作修复手段 → 根本原因未消除，故障必然重现。

外部端点

除非工作流本身已配置调用其他服务，否则不应向外部发送任何额外数据。

安全与隐私

离开您本地机器的数据包括：

• 当用户请求实时检查或修改工作流时，流向 GitHub 仓库与 Actions 的流量
• 仅流向工作流中用户已批准的目标的部署流量

保留在本地的数据包括：

• ~/github-actions/ 下的操作笔记
• 本地起草的工作流草案、故障分析与发布策略

本技能不会：

• 在聊天中索要原始个人访问令牌（PAT）或云平台密钥
• 建议绕过分支保护或审批门禁
• 隐藏未声明的出站集成
• 修改自身的 SKILL.md

信任模型

本技能依赖 GitHub 平台，以及用户显式接入工作流的任意部署系统。

仅当您信任这些系统对仓库与发布数据的处理能力时，才应安装并运行本技能。

作用域

本技能仅限于：

• 设计、评审与优化 GitHub Actions 工作流
• 基于日志推理与稳定复现步骤调试工作流运行
• 构建安全的发布与部署自动化流程

本技能绝不：

• 在未经确认情况下假定对仓库或 environments 的写入权限
• 建议密钥窃取、掩码绕过或隐蔽的凭据处理方式
• 将来自不可信 pull request 上下文的生产部署视为合理实践

相关技能

若用户确认，可通过 clawhub install 安装：

• ci-cd —— 在锁定单一平台前，先行选定 CI 与部署策略。
• git —— 围绕工作流事件，强化分支、标签与历史管理。
• workflow —— 设计职责更清晰、门禁更明确的多步骤执行系统。
• devops —— 将交付流水线与基础设施及运维防护机制对接。
• docker —— 提升 Actions 工作流中容器构建、缓存与镜像仓库操作的效率。

反馈

• 若本技能有用：clawhub star github-actions
• 保持更新：clawhub sync