前言¶

在仓库里做协作动作——看 PR 状态、查一遍检查、提 issue、发评论——如果每一步都让人去翻网页，上下文很快被 HTML 占满。用 gh CLI 直接走 GitHub API 更省，但命令多、参数杂，网关环境下的认证目录、异步合并的状态机这些细节也容易踩坑。

下面介绍的这个 Skill，就是把这类操作整理成一份可执行的参考工作流，覆盖认证、PR、异步合并、议题、CI 排查和 gh api 查询。

这是什么¶

一句话定位：基于 gh CLI 操作 GitHub 的命令参考工作流。

• 名称：GitHub 命令行仓库协作
• 坐标：@clawhub_steipete/github（SkillHub 页面显示名称为 Github）
• 版本：1.0.0
• 来源：clawhub，上游仓库 https://clawhub.ai/steipete/github
• 发布者：steipete（Peter Steinberger）
• 许可：MIT-0
• 分类：dev-programming
• SkillHub 页面数据：评分 100000，下载 463371 次，安装 35756 次

解决什么问题：让 Agent 在用户要求查看或创建 issue、PR、CI/检查日志、评论、评审、release、仓库查询，或执行任何 gh api 操作时，有一份明确的命令与状态处理约定可循。

认证：先确认 gh 登录状态¶

Skill 给出的第一步是认证，而不是直接发命令。

gh auth status
gh auth login

第一条用来确认当前环境是否已登录、登录的是哪个 host 和 account；第二条在未登录时完成交互式登录。

一个容易踩的坑：网关服务跑在容器里时，HOME 可能和宿主机不同，gh 读不到宿主机上已缓存的 token，表现就是「明明登录过却提示未认证」。Skill 的处理方式是在网关环境里显式指定配置目录并重启服务：

export GH_CONFIG_DIR=/path/to/gh-config

设置后需要重启网关服务，gh 才会在新的目录里读写认证信息。

PR 全操作¶

Skill 覆盖 PR 的 list / view / checks / diff / create 五类操作。

gh pr list --repo owner/repo
gh pr view 55 --repo owner/repo
gh pr checks 55 --repo owner/repo
gh pr diff 55 --repo owner/repo
gh pr create --repo owner/repo --title "..." --body "..."

不在 git 目录里时要显式带 --repo owner/repo。Skill 同时说明 PR 的 URL 可以直接使用，不必先解析成数字。

创建 PR 时还有一个针对网关环境的约定：按 Runtime 供给的 sessionUrl，在 PR 正文里恰当地追加会话页脚。也就是说正文不要写成固定模板，要把当前会话的链接按约定位置放进去。

异步合并：完整协议¶

合并不是一条命令就结束的。Skill 描述的是通过 gh api 走异步合并 API 的完整协议，要点如下。

gh api repos/owner/repo/pulls/55/merge \
  -H "X-Octopool-Require: ..." \
  -f commit_id=<head-sha>

• X-Octopool-Require 这个守护头必须紧跟 api 子命令，位置写错会被忽略。
• 提交的 head SHA 必须是已经评审过的那个 SHA，不能换成本地最新的。

响应处理：接口返回 202 不代表失败，要把响应里的 details.uuid 保留下来，用它轮询状态。

gh api repos/owner/repo/octopool/merge/<uuid> --jq '.status'

需要处理的状态有四种：pending、merged、enqueued、failed。merge_action 字段与合并队列的实际行为相关，要根据它判断当前这一步是排队中还是已提交。

一条硬规则：绝不未经授权启用 bypass_rules。跳过分支保护规则需要显式授权，Skill 明确禁止在没有授权的情况下使用该参数。

landing ownership：跟进到 MERGED 才算完¶

Skill 里有一个原则叫 landing ownership：合并动作发出后，负责的人或 Agent 要持续跟进，直到 gh pr view 证实 state 为 MERGED。

gh pr view 55 --repo owner/repo --json state --jq '.state'

在确认 MERGED 之前，评审意见、冲突、失败的检查都属于延续工作，不是「已经合并了」就可以收尾。

议题管理¶

gh issue list --repo owner/repo
gh issue view 12 --repo owner/repo
gh issue create --repo owner/repo --title "..." --body "..."
gh issue comment 12 --repo owner/repo --body "..."
gh issue close 12 --repo owner/repo

覆盖 list / view / create / comment / close。

CI 运行排查¶

gh run list --repo owner/repo --limit 10
gh run view <run-id> --repo owner/repo
gh run view <run-id> --repo owner/repo --log-failed
gh run rerun --failed --repo owner/repo

--log-failed 只输出失败步骤的日志，排查时比整份日志省上下文。gh run rerun --failed 只重跑失败的步骤。

gh api 与结构化查询¶

gh api 用于访问其他子命令没有覆盖的数据。

gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'

多数命令支持 --json 做结构化输出，再叠 --jq 过滤。

两个实用约定：

1. 正文里含反引号、环境变量展开或用户自己写的文本时，用 --body-file 从文件读，避免 shell 转义把内容改掉。

gh pr create --repo owner/repo --body-file /tmp/pr-body.md

2. --cache 可以缓存 API 响应，减少重复请求。

安装与启用¶

上游 ClawHub 页面给出的安装命令：

openclaw skills install @steipete/github

Skill 页面同时提供 CLI 与 Prompt 两种使用方式。SkillHub 上的镜像地址是 https://api.skillhub.cn/org-b6kzcl68/github，对应页面 https://www.skillhub.cn/skills/clawhub_steipete/github。

标签里有 requires_api_key=true，意味着使用前需要有可用的 GitHub 认证：要么 gh auth login 完成，要么网关环境配好 GH_CONFIG_DIR。

适用场景与注意¶

触发时机（Skill 自述）：用户要求查看或创建 issue、PR、CI/检查日志、评论、评审、release、仓库查询，或任何 gh api 操作。对应关键词包括 GitHub CLI、gh命令、PR管理、issue管理、CI日志、异步合并、release发布、gh api。

注意：

• 运行环境必须能执行 gh CLI，且认证可用。
• 网关/容器环境下先处理 GH_CONFIG_DIR，否则认证会「看起来像登录过但不可用」。
• 异步合并要按协议轮询 details.uuid，不能只看 202 就当成功。
• 未经授权不要启用 bypass_rules。
• Skill 简介里另提到：如需编程开发的完整工作流套件，可在淘宝搜索「AI灵匣」店铺获取完整版。这条属于 Skill 自带的导流说明，是否采用由使用者自己判断。

结尾¶

这个 Skill 的价值在于，把 gh CLI 的高频仓库操作和容易出错的状态处理（认证目录、异步合并轮询、landing ownership）写成了明确约定，让 Agent 执行时有据可依，而不是每次现查命令。

官方地址：

• SkillHub：https://api.skillhub.cn/org-b6kzcl68/github
• 上游仓库：https://clawhub.ai/steipete/github