github-ops

GitHub 操作

交付所要求的 GitHub 状态，而不是只执行出看似成功的命令。200、201、 202 或 204 响应只能证明 GitHub 接受了请求；不能证明所有要求的字段都已更改、 邀请已接受、异步任务已完成，或用户的业务目标已达成。

按操作选择参考文档

只阅读任务所需的参考文档：

任务	参考文档
创建、审查、合并、关闭、比较或收敛 PR；清除已获批准的 PR 正文修订；退役远程 PR 分支	references/pr_operations.md
创建、编辑、搜索、转移、关闭或批量管理议题	references/issue_operations.md
检查、克隆、创建、编辑、重命名、存档、转移、更改可见性或删除仓库	references/repository_operations.md
在保持常用账号处于活动状态的同时，复制其他账号可访问的仓库；配置私有副本和上游同步	references/multi_account_repository_sync.md
检查或更改协作者、团队、基础权限、成员权限或组织 2FA	references/organization_access_and_settings.md
保护默认分支，同时允许协作者通过 PR 贡献；盘点账号范围内的保护缺口、将基准配置应用到多个仓库，并通过实际推送验证执行效果	references/branch_protection.md
触发、检查、重新运行、取消或清理 Actions；管理密钥或变量	references/workflow_operations.md
减少 CI 邮件过载、Actions 额度耗尽、无关检查或重复运行；判断模板或产品实际需要什么	更改运行器或通知之前，先阅读 references/ci-demand-and-notifications.md
构建并发布 Docker/OCI 镜像到 GitHub Container Registry（GHCR）	references/ghcr_publishing.md
使用原始 REST/GraphQL 端点、分页、速率限制、webhook 或 Enterprise 主机	references/api_reference.md
构建脚本、重试、批量操作或机器可读输出	references/best_practices.md

对于本地 Git 恢复、工作区脏状态、bundle 或丢失的提交，请使用 git-safety-net。 此技能负责管理 GitHub 托管的状态。 对于仓库副本，还要处理每个远程仓库的身份验证和同步设置。

通用操作约定

1. 在操作 GitHub 前对请求分类

• **回答、检查、诊断或审查：**只读。不要创建 PR、议题、评论、邀请、工作流运行或更改设置。
• **创建、更改、合并、关闭、授予、撤销、发布或删除：**已授权执行所述状态更改。将目标和影响范围限制在该请求之内。
• **具有破坏性、公开、涉及凭据、会触发生产环境或对外沟通的操作：**必须明确具体目标、后果和恢复路径。如果用户未提供所有重要选项（例如仓库所有者、可见性或消息内容），应在写入前停止。

不要因为修复方案看起来显而易见，就把只读调查转变为修改操作。 不要发送当前任务未授权的评论、审查、议题或邀请，也不要擅自决定其接收者或内容。

对于已授权的贡献者，应根据其持续贡献角色评估仓库访问权限，而不只是根据今天的读取或同步命令。仓库的 Write 访问权限与更新默认分支的权限是两个独立的决定。遵循用户选择的贡献范围；通过分支保护和 PR 审查控制合并，而不是擅自将贡献者的权限降为 Read。仅有诊断结果仍不代表已获准授予权限。

2. 绑定身份、主机和目标

首次写入前，验证当前账号并解析完整限定目标：

gh auth status --hostname HOST
gh api --hostname HOST user --jq '.login'
gh repo view HOST/OWNER/REPO \
  --json nameWithOwner,visibility,isPrivate,viewerPermission,url

对于 github.com，OWNER/REPO 已足够。不要在常规诊断中使用 gh auth status --show-token， 也不要打印、粘贴或记录令牌。

在当前会话中首次推送到远程端之前，读取其实时可见性：

gh repo view OWNER/REPO \
  --json nameWithOwner,visibility,isPrivate,stargazerCount,forkCount,url

将身份绑定到将执行写入的接口。CLI 身份不能证明连接器、浏览器、REST 客户端或 Git SSH 身份。根据用户授权的任务确定预期操作者；仓库所有者和可用凭据都不会自动决定该操作者。对于连接器，使用同一连接器执行只读的当前用户操作，并确认其操作者。如果该接口无法显示操作者，则使用已验证的 CLI 通道执行授权写入；不要通过发布测试评论来探明其身份。

对于已授权的 gh API／托管状态写入，请使用捆绑的校验调用。将 <github-ops-dir> 解析为包含此 SKILL.md 的目录；从任务工作目录通过该路径运行辅助程序。其可执行参数和拒绝约定见 checked_gh.py。

uv run python <github-ops-dir>/scripts/checked_gh.py --expected-login <EXPECTED_LOGIN> --host HOST
uv run python <github-ops-dir>/scripts/checked_gh.py --expected-login <EXPECTED_LOGIN> --host HOST -- pr edit <NUMBER> -R OWNER/REPO --title '<AUTHORIZED_TITLE>'

第一条命令为只读操作。第二条命令会解析当前凭据、检查 GET /user，并将同一凭据固定用于一次命令。若操作者不匹配或未知，程序会在执行前退出。它仅保护 gh，不保护连接器调用、浏览器操作或 Git 推送。身份验证／配置命令会被拒绝；仍需任务授权、准确目标和独立回读。对于仓库范围的命令，提供 -R OWNER/REPO；对于 gh repo，提供明确的仓库操作数。包装程序会使用已校验的主机限定该目标，从子进程中移除继承的 GH_REPO 和其他令牌变量，并拒绝冲突的主机操作数。仅进行身份读取时，省略命令。组织密钥／变量操作则使用明确的 --org 范围；个人 Codespaces 密钥使用 --user。即使正文／标题／字段值看起来像标志或 URL，也会保持原样。公共 API 的绝对 URL 使用 api.github.com；相对 API 端点仍受支持。 切换账号、凭据、主机或接口会使先前的身份凭证失效。下次写入前重新检查；不要重复使用先前会话的通过结果。

参考示例展示原生 gh 操作语法。通过将这些参数放在辅助程序的 -- 之后，并提供明确的仓库或账号范围，执行托管状态变更；裸用 gh 仍适用于回读以及单独授权的身份验证／配置操作。如果内置命令拒绝某种操作数格式，请通过同一辅助程序使用其支持的显式 REST／GraphQL 等效操作；不要绕过操作者检查。调用失败或超时并不能证明变更未发生：重试前先读取确切目标。

对于事件归因，将事件 ID／时间、操作者和接口与 ChatGPT 执行账号分开保存。评论作者的 login 和 performed_via_github_app 可确定 GitHub 操作者／应用，而非 ChatGPT 邮箱。会话的创建者身份和今天的身份验证文件不能证明其历史执行账号。缺失的关联信息应保持未知。

3. 读取当前权威状态并预览差异

使用 GitHub 托管状态，而非过时的本地引用或记忆中的设置。只采集证明所请求状态转换所需的字段。在进行重要写入之前，明确说明以下计划：

Target: fully qualified repository, organization, PR, issue, run, or account
Current: authoritative fields and immutable IDs/SHAs
Requested: exact field or state transition
Blast radius: people, repositories, forks, runs, or public surfaces affected
Recovery: exact inverse operation or explicit “not recoverable”
Readback: independent GET/CLI query and expected result

如果用户已授权这一确切后果，就执行操作。不要再要求形式化的二次确认。如果目标、范围、公开可见性、删除、接收方或恢复方式仍有歧义，请在写入前暂停。

4. 选择输入契约确实支持该变更的接口

按以下优先顺序选择：

1. 专门为此设计的 gh 子命令；
2. 针对单个资源或权威回读的文档化 REST 端点；
3. 仅支持所需变更/查询，或需要组合相关数据时使用 GraphQL；
4. 设置没有受支持的 API 输入时，使用文档化的 GitHub UI。

响应字段并不自动就是可写字段。使用 PATCH 前，应将目标键与该操作当前的请求体参数进行对比，而不是与 GET 返回的数据结构进行对比。GitHub 可能会忽略不受支持的键，同时仍返回成功响应。不要仅为了让命令运行而切换 API 类型。

使用 gh api 时，应明确指定方法。添加 -f 或 -F 会将默认方法改为 POST；筛选后的 GET 请求必须包含 -X GET。

5. 只执行一次变更；不要对模糊结果重试

• 在操作支持的情况下，固定指定仓库、对象编号、分支、运行 ID、用户名和预期 SHA。
• 不要盲目重试评论、邀请、工作流分发、发布或 PR/议题创建等非幂等写入。发生超时或 5xx 后，先回读以确定首次请求是否已生效。
• 对批量变更，先冻结并显示有限的目标列表，然后逐个处理，并记录每项结果。绝不要将未经审核的实时查询直接传入具有破坏性的 xargs 命令。
• 不要绕过仓库钩子、必需检查、分支保护、签名或可见性变更后果确认。

6. 通过独立回读验证

执行一次全新的读取，不要依赖变更响应或本地缓存的引用：

变更	必需的验收证据
PR 合并/关闭/编辑	PR 状态；若是否落地很重要，还需验证获取到的基分支上已接受的行为
分支删除	托管端分支/引用不存在；本地远程跟踪引用的清理需单独检查
议题/评论/审查	目标对象准确存在一次，且状态/内容符合预期
仓库创建/编辑/可见性	完全限定的仓库回读与所有者、可见性及请求字段一致
协作者/团队权限	若邀请待处理，则检查邀请状态，然后检查有效权限；撤销权限时还要找出仍然有效的基础权限/团队授权
组织设置	全新的组织/设置读取返回所有请求字段；仅限 UI 的设置需通过 UI 回读，并检查任何可用的 API 信号
2FA 要求	预先检查受影响的账户，确认 UI 设置，通过 API 回读，然后审计成员/外部协作者
工作流分发/重新运行/取消	目标运行 ID 达到预期状态；命令被接受不代表操作已完成
密钥/变量变更	检查元数据和使用方行为，绝不泄露密钥值

对于异步状态，应在有时间上限的情况下轮询；若尚未观察到终态，则报告 pending。如果回读结果不符，则报告 failed/no-op 或 partially applied，列出不匹配的字段，并保留恢复途径。绝不要仅凭写入回执就声称“已完成”。

7. 报告业务结果

最后如实报告以下四种状态之一：

• 已变更并验证 — 已通过独立读取确认请求的状态；
• 已满足 — 无需写入；
• 待处理 — 已接受但尚未达到终态，并注明下一步权威检查；
• 失败/无操作或部分完成 — 请求状态与观察到的状态不符，并说明恢复方式和未解决的风险。

8. 仅针对指定写入操作进行身份验证

身份验证仅适用于获授权的操作；它不是重新打开已获授权的精确写入操作的理由。启动交互式浏览器或设备流程前，请说明 GitHub 应用、当前活动账户、目标主机以及确切的权限变更。说明后，继续完成浏览器可以完成的步骤。Confirm access 页面是重新身份验证提示；仅凭其标题，不能认定必须由用户本人亲自操作。对于已验证的浏览器账户、主机和确切操作，请通过可信页面，使用已获授权的常规密码管理器流程，不要提取或显示凭据。从第一个尚未完成的步骤继续，然后独立读取实际操作的结果；完成重新身份验证并不能证明写入已发生。

遇到确实需要用户亲自操作的 MFA 或硬件密钥验证、尚未解决的账户选择，或无法使用经批准的凭据途径时，请交由用户处理。不得绕过需要亲自操作的验证。不要仅仅因为常规流程需要交互，就请求更广泛的权限范围、改用其他账户或请求无关的审批；对于已获授权的写入操作，不要再次询问。

不要在终端输出、URL、参数、已提交的文件或报告中暴露凭据值。生产主机上的只拉取型注册表凭据，不代表获得了发布授权。确认当前凭据已获授权且适用于确切的写入操作后，应重复使用该凭据；使用临时的本地 Docker 配置，并在操作完成后删除该配置。GHCR 发布有单独的预检和摘要回读流程；构建或推送镜像前，请加载 references/ghcr_publishing.md。

高影响操作边界

• 创建仓库必须明确指定 OWNER/REPO 和可见性。切勿默认将通用示例设为 --public；公开是产品决策。
• 更改仓库可见性可能会暴露代码、Actions 日志、构件、分支和历史记录。只有在相关后果和确切仓库都已获授权后，才使用 gh repo edit --visibility ... --accept-visibility-change-consequences，然后读取变更结果以确认。
• 合并、删除分支、创建／删除／转移仓库、更改仓库可见性、组织范围的权限、更改 2FA 强制策略以及轮换密钥，都必须参照相应操作专用的参考文档。
• PR 和议题标题格式属于仓库策略。请检查模板、贡献指南、检查项或近期已接受的示例；不要凭空设定通用的 JIRA 前缀。
• 企业策略可能覆盖组织或仓库控制。明确保留 HOST，并在较低层级无法更改强制状态时予以说明。

安全的只读速查

gh pr list -R OWNER/REPO --state open --json number,title,state,url
gh pr view 123 -R OWNER/REPO --json number,title,state,headRefOid,baseRefOid,url
gh issue list -R OWNER/REPO --state open --json number,title,state,url
gh workflow list -R OWNER/REPO
gh run list -R OWNER/REPO --limit 20 \
  --json databaseId,status,conclusion,headSha,url
gh api -X GET 'repos/OWNER/REPO/branches?per_page=100' --paginate --jq '.[].name'

使用 --json／--jq 做出判断。面向用户阅读的格式化输出仅供阅读，不可用于解析。