GitHub CLI (gh)
通过命令行与GitHub交互:仓库、Release、Issue、PR、讨论、搜索、代码审查和Actions。
已在 gh 2.95.0 版本上验证。
Agent 指南
- 对于已知的远程文件或目录,使用
gh repo read-file/gh repo read-dir(在gh2.95 中为预览功能)。对于较旧的gh版本或仅需 API 的情况,请使用 API 模式 中的内容 API 回退方案。 - 当任务需要在文件间搜索或探索不熟悉的代码且路径未知时,克隆到临时目录(
gh repo clone owner/repo <temp-dir> -- --depth 1)并使用本地文件读取和搜索工具。 - 对于读取/查看操作,优先使用默认文本输出而非
--json——这更节省token。仅在需要以编程方式提取特定字段时,才使用带--jq的--json。要发现支持的字段,先运行不带字段列表的--json命令,然后只请求你需要的字段。 - 查看日志或差异时,在获取完整内容前先限定输出范围(例如
--name-only、--log-failed)。 - 在已克隆的仓库内运行时,无需使用
--repo标志——默认使用当前目录的仓库。对于gh api,使用显式路径(repos/OWNER/REPO/...)或设置GH_REPO环境变量。 - 将此技能用于已覆盖的工作流。当缺少某个需要的标志或字段、命令因未知/已更改的标志失败,或命令标记为预览时,请检查特定命令的帮助(例如
gh pr diff --help)。
安全性
- 写操作(
create、edit、comment、review、close、merge、delete、rerun、run cancel、workflow run/enable/disable、讨论变更)会修改 GitHub 状态。执行前请先与用户确认,尤其是在你并非所有者的仓库上。 gh api配合--method POST/PUT/PATCH/DELETE会发送写请求。请仔细检查端点和载荷。默认方法为 GET(安全);添加-f/-F参数会将默认方法切换为 POST。- 破坏性操作(
delete、close、merge --admin)可能是不可逆的。需要明确的用户确认。
前提条件
在运行命令前,验证 gh 已安装并认证:
gh --version
gh auth status
如果未认证,请引导用户通过 gh auth login 完成认证。
公共标志
这些标志在许多命令组中都可用,但支持情况因命令而异:
--repo OWNER/REPO—— 指定不同的仓库(默认:当前目录的仓库)。也接受完整 URL。--json FIELDS—— 以 JSON 格式输出,包含指定字段。不传值可列出可用字段。--jq EXPRESSION—— 使用 jq 语法过滤 JSON 输出。需要配合--json。--template STRING—— 使用 Go 模板格式化 JSON 输出(--jq的替代方案)。--web—— 在浏览器中打开资源,而非在终端中显示。--limit N—— 列表命令的最大结果数(默认通常为 30)。
仓库
查看
显示仓库的描述、README、星标数、语言分布及其他元数据。
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
克隆
在本地克隆仓库。自动配置远程仓库,对于 fork 还会设置上游远程仓库。
gh repo clone owner/repo [target-directory]
读取远程仓库内容
对于已知文件或目录的快速读取,使用仓库读取命令(在 gh 2.95 中为预览功能):
# 已知文件
gh repo read-file src/main.py --repo owner/repo --ref main
# 已知目录
gh repo read-dir src --repo owner/repo --ref main
# 较旧 gh 版本的备选方案
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
关于输出格式、文件大小限制和目录列表注意事项,请参阅 API 模式。对于多文件探索,请改用克隆(参见 Agent 指南)。
列出仓库
列出用户或组织拥有的仓库,可设置语言和可见性过滤器。
gh repo list owner --limit 30
Releases
列出
按创建日期(最新在前)列出仓库中的 Releases。默认显示所有 Releases,包括预发布和草稿。
gh release list --repo owner/repo --limit 10
标志:
--exclude-pre-releases—— 排除预发布--exclude-drafts—— 排除草稿
关键 JSON 字段:tagName、name、publishedAt、isLatest、isDraft、isPrerelease、isImmutable
查看(更新日志、资产)
显示 Release 的更新日志正文、标签、资产和元数据。省略标签可查看最新 Release。
gh release view --repo owner/repo # 最新 Release
gh release view v1.2.0 --repo owner/repo # 特定标签
gh release view v1.2.0 --json tagName,body,assets,publishedAt
关键 JSON 字段:tagName、name、body、assets、author、publishedAt、isDraft、isPrerelease、isImmutable、url
Issues
列出
列出仓库中的 Issue,可按状态、标签、分配人或搜索查询进行过滤。默认仅显示打开的 Issue。
gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"
标志:
--state VALUE——open(默认)、closed、all--label NAME—— 按标签过滤(可重复使用)--assignee LOGIN—— 按分配人过滤(@me为自己)--search QUERY—— GitHub 搜索语法
关键 JSON 字段:number、title、state、stateReason、author、labels、assignees、createdAt、updatedAt、url
查看
显示 Issue 的标题、正文、标签、分配人和状态。使用 --comments 可包含完整评论线程。
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
创建
使用标题、正文、标签和分配人创建一个新 Issue。
gh issue create --title "Bug: description" --body "Details..." --label bug --assignee user1
编辑
更新 Issue 的标题、正文、标签、分配人或里程碑。所有标志可在一次调用中组合使用。
标志:
--title TEXT/--body TEXT—— 更新标题或正文--add-label NAME/--remove-label NAME—— 修改标签--add-assignee LOGIN/--remove-assignee LOGIN—— 修改分配人--milestone NAME/--remove-milestone—— 设置或移除里程碑
评论
在现有 Issue 中添加评论。
gh issue comment 123 --body "Comment text"
关闭 / 重新打开
关闭或重新打开 Issue。可选地指定关闭原因并留下评论。
gh issue close 123 --comment "Fixed in PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
关闭原因:completed(默认)、not planned、duplicate。
状态
显示与你相关的 Issue 摘要:分配给你的、提及你的以及你创建的。
gh issue status
关于 Issue 类型、子 Issue、父级关系、阻塞依赖项及其 JSON 字段(需要支持的 GitHub 主机),请参阅 Issue 参考。
Pull Requests
使用这些命令来查看和检查 PR。对于创建、合并、审查和管理 PR,请参阅 Pull Requests 参考。
列出
列出仓库中的 Pull Request,可按状态、作者、标签或搜索查询进行过滤。默认仅显示打开的 PR。
gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot
标志:
--state VALUE——open(默认)、closed、merged、all--draft—— 按草稿状态过滤--author LOGIN/--assignee LOGIN—— 按作者或分配人过滤--label NAME—— 按标签过滤--search QUERY—— GitHub 搜索语法--app NAME—— 按 GitHub 应用作者过滤(例如dependabot)
关键 JSON 字段:number、title、state、author、headRefName、baseRefName、labels、reviewDecision、isDraft、statusCheckRollup、files、commits、reviews、url
查看
显示 PR 的标题、正文、审查状态、检查和其他元数据。不传参数时,显示当前分支的 PR。使用 --comments 可包含评论线程。
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
状态
显示与你相关的 PR 摘要:当前分支的 PR、你创建的 PR 以及需要你审查的 PR。
gh pr status
讨论
使用 gh discussion 进行仓库讨论(在 gh 2.94 中为预览功能)。以读取命令开始,并使用 --help 验证标志,因为命令集是预览的:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
关于创建、编辑、评论、回复线程、JSON 输出格式和 GraphQL 回退模式,请参阅 讨论参考。
搜索
跨 GitHub 搜索 Issue、PR、代码、提交和仓库。对于单个仓库,使用 gh issue list / gh pr list;对于跨仓库或所有者范围的查询,使用 gh search ...。
有关完整的搜索查询语法,请参阅 GitHub 搜索文档。有关每个子命令特有的标志,请运行 gh search <subcommand> --help。
速率限制: 搜索 API 的速率限制比核心 API 更严格。代码搜索限制最严格(已验证身份约 10 次/分钟;需要身份验证)。其他搜索命令允许已验证身份约 30 次/分钟,未验证身份约 10 次/分钟。使用 gh api rate_limit --jq '.resources | {search, code_search}' 检查当前配额。
何时改用克隆: 请参阅 Agent 指南了解何时克隆而非使用 API。
机器人和应用: 对于 GitHub 应用作者(如 Dependabot),使用 --app dependabot;--author dependabot 过滤用户账户,而非应用作者。
侦察: 当搜索不熟悉的仓库时,首先检查其主要语言以选择正确的 --extension 和 --language 值:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
Issues
使用关键字、标签、状态或 GitHub 搜索语法跨仓库搜索 Issue。
gh search issues "error handling" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo
关键标志:--repo、--owner、--state、--label、--assignee、--author、--app、--involves、--comments、--match、--sort、--include-prs。
PR
跨仓库搜索 Pull Request。支持按作者、审查状态、合并状态和草稿状态过滤。
gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo
关键标志:--repo、--owner、--state、--merged、--draft、--author、--assignee、--app、--label、--review、--review-requested、--base、--head、--checks、--sort。
代码
跨 GitHub 仓库搜索文件内容。仅返回匹配的行(不包含行号,不包含周围上下文)。适用于定位包含特定模式的文件,但随后应通过文件读取或克隆仓库来理解代码逻辑。
限制: 使用旧版搜索引擎(结果可能与 github.com 不匹配)。仅搜索默认分支。仅索引小于 384 KB 的文件。每个查询必须至少包含一个搜索词(仅限限定符的搜索,如 --extension ts 单独使用会失败)。不支持 --sort 或 --order —— 结果始终按相关性排序。
gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
关键标志:--repo、--owner、--extension、--filename、--language、--match、--size。
关键 JSON 字段:path、repository、sha、textMatches、url。
textMatches 字段提供带有字符级别匹配位置的片段上下文——当需要比默认文本输出更多上下文时,使用 --json path,textMatches。
提交
按提交消息文本、作者、提交者日期或哈希值搜索提交。
gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
关键标志:--repo、--owner、--author、--committer、--author-date、--committer-date、--author-name、--author-email、--hash、--merge、--sort。
仓库
按关键字、语言、主题、星标数、许可或所有者搜索仓库。注意:此子命令上不可使用 --repo —— 使用 --owner 按所有者过滤。
gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
关键标志:--owner、--language、--topic、--stars、--forks、--license、--created、--updated、--match、--sort、--include-forks、--visibility。
排除限定符(连字符前缀)
包含排除项的搜索查询(如 -label:bug)需要特殊语法,以避免 shell 标志解释。所有标志(例如 --limit)必须出现在 -- 之前;-- 之后的所有内容都被解释为搜索查询文本:
# Unix-like shells
gh search issues -- "my query -label:bug"
# PowerShell
gh --% search issues -- "my query -label:bug"
…
[已截断用于翻译]