gh-cli

GitHub CLI (gh)

对于可通过命令行完成的 GitHub 工作，优先使用 gh：检查仓库、管理议题和拉取请求、查看 Actions 运行、管理发布和 gist，以及调用经过身份验证的 GitHub API。

如需了解确切的标志和当前行为，请运行 gh help、gh <command> --help，或阅读官方 GitHub CLI 手册。

操作原则

• 对于 GitHub 操作，优先使用 gh，而不是临时的浏览器操作，尤其是在需要复制、筛选或编写脚本处理输出时。
• 修改前先检查。如果上下文、仓库、分支或账户不确定，请先运行只读命令。
• 如果当前不在目标仓库的本地检出目录中操作，请使用 --repo OWNER/REPO 明确指定仓库范围。
• 使用 --json 配合 --jq 获取结构化输出，而不是解析面向用户的表格。
• 在自动化中避免交互式提示。只有在检查命令帮助并确认操作安全后，才使用 --body-file、--title、--label、--assignee、--confirm 或 --yes 等标志。
• 将破坏性操作视为高风险：删除、关闭、合并、归档、删除发布、更新密钥、取消工作流和更改权限都需要额外验证。

初步检查

使用 gh 前，请先检查基本信息：

gh --version
gh auth status
git remote -v
gh repo view --json nameWithOwner,defaultBranchRef,url

有用的上下文命令：

gh status
gh repo view --web
gh browse --no-browser
gh config list

对于 GitHub Enterprise 或非当前仓库，请使用 gh help 中记录的相应主机名和仓库标志。

常见工作流

仓库

gh repo view OWNER/REPO
gh repo clone OWNER/REPO
gh repo fork OWNER/REPO --clone=false
gh repo sync OWNER/REPO --branch BRANCH
gh repo list OWNER --limit 100 --json name,visibility,url

议题

gh issue list --state open --limit 50
gh issue view NUMBER --comments
gh issue create --title "Title" --body-file body.md
gh issue comment NUMBER --body-file comment.md
gh issue edit NUMBER --add-label label --add-assignee @me

拉取请求

gh pr status
gh pr list --state open --limit 50
gh pr view NUMBER --comments --files
gh pr diff NUMBER
gh pr checkout NUMBER
gh pr create --fill
gh pr review NUMBER --comment --body-file review.md
gh pr checks NUMBER --watch

创建或更新 PR 前，请使用 git status --short、git branch --show-current 和 git log --oneline --decorate -n 10 检查本地 Git 状态。

Actions 和工作流

gh run list --limit 20
gh run view RUN_ID --log
gh run watch RUN_ID
gh workflow list
gh workflow run WORKFLOW --ref BRANCH

只有在确认目标分支、工作流名称和所需输入后，才能使用工作流调度命令。

发布

gh release list
gh release view TAG
gh release create TAG --notes-file notes.md
gh release upload TAG path/to/asset

发布或编辑发布内容前，请确认标签、生成的说明和资源。

GitHub API

当 gh 没有对应的专用命令，或任务需要直接调用 GraphQL 或 REST 端点时，请使用 gh api。

gh api repos/OWNER/REPO
gh api graphql -f query='query { viewer { login } }'
gh api --paginate repos/OWNER/REPO/issues

筛选时优先使用 --jq；只有当端点可能返回多页结果时，才使用 --paginate。

输出处理

• 对于脚本，优先使用稳定的机器可读输出：

  gh pr view NUMBER --json title,author,state,mergeable --jq '{title, author: .author.login, state, mergeable}'
  

• 对于 Markdown 正文，请将内容写入临时文件或现有文件，并传入 --body-file / --notes-file。长文本应避免复杂的 shell 引号处理。

• 如果输出可能包含密钥、令牌、私有 URL 或用户数据，请进行概述，而不是原样粘贴。

身份验证和权限

使用 gh auth status 确认当前账户和主机。如果命令因权限范围不足而失败，请检查错误，然后查阅特定权限范围的官方帮助。常见解决方法包括在交互使用时运行 gh auth refresh，或在自动化中设置 GH_TOKEN。

除非任务明确要求且输出不会暴露，否则切勿通过 gh auth token 打印令牌。

不要使用 gh 的情况

• 对于提交历史、blame、分支操作、暂存、变基和本地差异，请使用本地 git。
• 对于本地代码理解，请直接读取文件或搜索仓库。
• 只有在任务需要仅限 UI 的功能、视觉检查或 gh 不支持的身份验证流程时，才使用浏览器。