github

GitHub

所有 GitHub 操作均使用 gh CLI。对于结构化且可解析的输出，优先使用 --json 和 --jq。如果当前不在配置了远程地址的 Git 仓库中，请使用 --repo owner/repo。使用 --web 在浏览器中打开任何资源。

前提条件与身份验证

安装

平台	命令
macOS	brew install gh
Debian/Ubuntu	sudo apt install gh
Windows	winget install GitHub.cli

身份验证

gh auth login           # interactive OAuth login
gh auth status          # check current auth and active account

所需的 OAuth 范围

范围	授予的访问权限
repo	私有仓库、议题、PR、提交、状态
read:org	组织成员身份、团队列表
workflow	触发和管理 GitHub Actions 工作流
gist	创建和管理 gist
delete_repo	删除仓库（默认不授予）
admin:org	管理组织设置、团队、成员
project	对 ProjectV2 看板的读写访问权限

无需从头重新进行身份验证，即可添加缺少的范围：

gh auth refresh --scopes repo,read:org,workflow

---

参考资料路由

用户意图	加载
创建/列出/查看/编辑/关闭议题、添加评论	references/issues.md
创建/列出/查看/审核/合并/编辑/关闭拉取请求	references/pull-requests.md
列出运行记录、查看日志、触发/重新运行/监控工作流、查看工件	references/ci-actions.md
创建/派生/克隆/查看/编辑/归档/删除仓库	references/repos.md
创建/列出/查看/编辑/上传/删除发布	references/releases.md
搜索仓库、议题、PR、代码、提交	references/search.md
通过 gh api 调用原始 REST/GraphQL、分页、速率限制	references/api.md
GraphQL 成本模型、批量查询、变更、速率限制	references/graphql-queries.md
多步骤工作流示例（PR 生命周期、CI 分诊、发布）	references/automation-workflows.md
创建/列出/查看/编辑/删除 gist	references/gists.md
列出组织、团队、成员	references/orgs.md

工作流模式

1. 根据上方路由表确定用户意图。
2. 加载对应的 references/<file>.md，查看命令语法和示例。
3. 根据需要，执行带有 --repo owner/repo 和 --json/--jq 的 gh 命令。
4. 出错时，查阅下方的错误处理表。

---

错误处理

错误	原因	解决方法
HTTP 401 Unauthorized	令牌已过期或被撤销	运行 gh auth login 重新进行身份验证
HTTP 403 Forbidden	权限不足或触发速率限制	检查 gh auth status 中的权限范围；检查 gh api rate_limit
HTTP 404 Not Found	仓库不存在、仓库为私有且没有 repo 权限范围，或资源已删除	验证仓库名称；运行 gh auth refresh --scopes repo
HTTP 422 Unprocessable Entity	请求载荷无效——缺少必填字段或验证错误	检查请求正文中的字段是否符合 API 架构
HTTP 429 Too Many Requests	超出 REST 速率限制（已验证身份时每小时 5000 次请求）	等待 X-RateLimit-Reset 时间戳；降低请求频率
GraphQL rate limit exceeded	每小时使用超过 5000 点	降低查询复杂度或等待；参见 references/graphql-queries.md
"no git remotes found"	在 git 仓库外运行 gh，且未指定 --repo	在命令中添加 --repo owner/repo
OAuth 权限范围不足	令牌缺少执行该操作所需的权限范围	运行 gh auth refresh --scopes scope1,scope2
重复的问题/PR 标题	这并非真正的错误——GitHub 允许重复标题，但创建前应先检查	先使用 gh issue list 或 gh pr list 搜索
归档的仓库阻止写入	仓库已归档；所有写入操作都会失败	使用 gh repo edit owner/repo --archived=false 取消归档，或改用其他仓库

启用调试日志以查看原始 HTTP 请求和响应：

GH_DEBUG=api gh pr list --repo owner/repo

---

校准规则

1. 优先使用 --json，而不是解析文本输出。 文本输出格式在不同 gh 版本之间并不稳定。始终使用 --json field1,field2 获取机器可读的输出。
2. 使用 --jq 在处理前尽量减少输出。 在数据源处进行筛选，而不是将大型 JSON 数据块传递给外部工具。--jq 在服务端运行，可减少传输的数据量。
3. 优先使用更高级别的命令，而不是原始 API。 使用 gh issue create，而不是 gh api repos/.../issues -X POST。高级命令会自动处理身份验证、分页和错误格式化。
4. 在 git 目录外始终使用 --repo。 在脚本或 CI 环境中，切勿依赖隐式仓库检测。始终显式传入 --repo owner/repo。
5. 仅在处理嵌套数据或批量数据时使用 GraphQL。 对于单资源获取以及载荷简单的变更操作，REST 编写更快捷、更易调试，且在速率限制下更可预测。

---

限制

• 需要网络 — 所有 gh 命令都需要互联网访问；不支持离线模式。
• GraphQL 点数额度 — 已认证用户每小时有 5000 点。复杂查询使用较大的 first/last 值时会更快消耗点数。请参阅 references/graphql-queries.md。
• 密钥只能写入 — gh secret set 可以使用，但没有 gh secret get。密钥值创建后无法检索。
• 组织管理员操作 — 管理组织设置、团队和 SAML 需要 admin:org 作用域，默认情况下不会授予该作用域。
• 构件保留期 — 工作流构件默认保留 90 天。过期的构件无法下载。