gh

gh

通过 gh CLI 执行 GitHub 操作。将所有常见操作——PR、议题、发行版、工作流运行、仓库、搜索——封装为符合惯例且节省令牌的调用。

这里的 git 仅用于只读操作——日志、差异、状态。不提交、不推送，也不通过此技能创建 PR。可搭配配套 easy-cheese 仓库中的 /plate，进行提交、推送和创建 PR——无论是单个还是堆叠式 PR。

---

CLI 规则

不要将 gh 的输出通过管道传给独立的 jq 二进制文件。 gh 自带 --jq 和 --template 标志；将它们内联使用可以避免启动 jq，也能避免触发某些执行环境采用的复合命令沙箱启发式规则。将 gh ... --jq 的输出通过管道传给 xargs 或 sed 等下游工具是可以的——关键是要在 gh 内完成 JSON 提取：

# wrong — needs jq binary, triggers a compound command
gh pr list --json number | jq '.[].number'

# right — inline jq, no pipe
gh pr list --json number --jq '.[].number'

# also fine — --jq inlined, then piped to xargs for a bulk op
gh pr list --json number --jq '.[].number' | xargs -I{} gh pr view {}

# Go template alternative
gh pr view 42 --json title --template '{{.title}}'

绝不要用 heredoc --body 编写议题或评论正文。 $(cat <<'EOF' ... EOF) 模式在正文包含 Markdown 标题时，可能触发“# 隐藏参数”沙箱启发式规则。应将正文写入文件，然后传入 --body-file：

gh issue create --title "flaky health-endpoint test" \
  --body-file "$TMPDIR/issue-body.md" --label bug

始终通过 --help 检查 JSON 字段名称。 它们与 GitHub REST API 中的名称不同：

gh pr list --help | sed -n '/JSON FIELDS/,/^$/p'

常见易错项：stargazerCount（而非 stargazersCount）、forkCount（而非 forksCount）、watchers（而非 watchersCount）。

---

拉取请求

PR 创建由 /plate 负责——此技能从 PR 创建后开始接手。

# Request review on an existing PR
gh pr edit 123 --add-reviewer @copilot

# View
gh pr list                                       # repo PRs
gh pr list --author @me                          # mine
gh pr list --search "is:open label:bug"          # full search syntax
gh pr view 123
gh pr view 123 --web
gh pr diff 123
gh pr diff 123 --exclude '*.lock'                # skip lockfile noise

# Status & checks
gh pr status                                     # PRs touching you
gh pr checks 123                                 # CI checks for the PR
gh pr checks 123 --watch                         # block until done

# Review & merge
gh pr review 123 --approve --body "LGTM"
gh pr review 123 --request-changes --body-file review.md
gh pr merge 123 --squash --delete-branch
gh pr merge 123 --auto --squash                  # auto-merge when checks pass
gh pr update-branch 123                          # bring up to date with base

# Lifecycle
gh pr close 123
gh pr reopen 123
gh pr ready 123                                  # un-draft
gh pr revert 123                                 # creates new revert PR
gh pr checkout 123                               # check out PR branch locally

有关 --jq 筛选模式和批量操作，请参阅 references/jq-recipes.md。 有关端到端 PR／发行版／CI 脚本，请参阅 references/automation.md。

---

议题

gh issue create --title "..." --body-file body.md --label bug
gh issue create --title "..." --assignee @me

gh issue list                                    # repo issues
gh issue list --label bug --state open
gh issue list --search "is:open label:bug sort:created-desc"

gh issue view 456
gh issue view 456 --web

gh issue edit 456 --add-label needs-triage
gh issue edit 456 --add-assignee @user
gh issue comment 456 --body-file comment.md

gh issue close 456
gh issue close 456 --duplicate-of 123
gh issue reopen 456
gh issue develop 456 --checkout                  # branch off the issue

---

CI／工作流／运行

gh workflow list
gh workflow run ci.yml --ref feature-branch
gh workflow run deploy.yml -f environment=production -f version=v1.2.3

gh run list                                      # all recent runs
gh run list --workflow=ci.yml --status=failure
gh run list --branch=main --limit 10

gh run view 789
gh run view 789 --log                            # full logs
gh run view 789 --log-failed                     # only failed jobs
gh run view 789 --web

gh run watch 789                                 # block until run completes
gh run rerun 789 --failed                        # re-run failed jobs only
gh run cancel 789

# Inspect a run programmatically
gh run view 789 --json status,conclusion,jobs \
  --jq '.jobs[] | select(.conclusion=="failure") | .name'

---

发行版

gh release create v1.0.0                         # interactive
gh release create v1.0.0 --notes-file NOTES.md
gh release create v1.0.0 --generate-notes        # auto-generate from PRs
gh release create v1.0.0 --draft
gh release create v1.0.0 dist/*.tar.gz           # upload assets at create time
gh release upload v1.0.0 dist/*.tar.gz           # add assets later

gh release list
gh release view v1.0.0
gh release download v1.0.0
gh release verify v1.0.0                         # supply-chain attestation

---

仓库与搜索

gh repo view                                     # current repo
gh repo view owner/repo --json description,stargazerCount,defaultBranchRef
gh repo clone owner/repo
gh repo fork owner/repo --remote
gh repo set-default                              # disambiguate origin

gh search repos "machine learning" --language=python --stars=">1000"
gh search code "TODO" --owner=myorg --language=rust
gh search issues "memory leak" --state=open
gh search prs "refactor" --created=">2024-01-01"

有关标签／codespace／gist／密钥操作，请参阅 references/extras.md。

---

身份验证

gh auth login                                    # interactive web login
gh auth login --clipboard                        # auto-copy OAuth code
gh auth status                                   # current identity
gh auth refresh -h github.com -s repo,workflow   # add scopes
gh auth setup-git                                # use gh as git credential helper

常见作用域：repo（私有仓库写入）、workflow（Actions）、admin:org（组织管理）、write:packages（注册表）。

如果调用返回 HTTP 401，请运行 gh auth refresh。如果返回 HTTP 403 Resource not accessible by personal access token，则表示缺少作用域——请重新运行 gh auth refresh -s <scope>。如需深入诊断，请参阅 references/troubleshooting.md。

---

不负责的事项

• 暂存、提交、推送、创建 PR、变基或以其他方式修改工作树——这些由 /plate 负责
• 代码质量审查——请使用专门的审查技能
• 创建 worktree——不在职责范围内
• 破坏性操作。 gh repo delete、gh release delete、 gh secret delete、gh ssh-key delete、gh codespace delete 及 类似不可逆命令不属于此技能。只有在获得用户明确确认后才能运行；绝不要将它们写入自动化流程。

易错点

• 复合命令 cd <dir> && git ... 可能被执行环境的裸仓库沙箱启发式规则拦截。请改用 git 的 -C <dir> 标志，或从 worktree 根目录运行。
• heredoc --body 配合 Markdown 标题 会触发“# 隐藏参数”防护——始终使用 --body-file。
• gh api 原始调用 更容易出问题，而且很少有必要。只要存在子命令包装器，就优先使用 gh pr ...、gh issue ...、gh run ...，而不是 gh api；仅在没有子命令包装器的端点上使用 gh api。
• 速率限制：gh api rate_limit 可显示当前配额。已认证请求的限额为每小时 5000 次，未认证请求为每小时 60 次。
• 默认仓库不明确：如果克隆包含多个远程仓库，请运行一次 gh repo set-default，或在每次调用时传入 --repo owner/name。

另请参阅

• references/jq-recipes.md — 用于 PR / 运行 / issue 查询的节省令牌 --jq 模式
• references/automation.md — 发布流程、 CI 监控、批量操作
• references/extras.md — 标签、codespaces、 gists、密钥/变量、项目、别名
• references/troubleshooting.md — 身份验证、 权限、速率限制、常见错误代码
• 官方手册：https://cli.github.com/manual