smy-skills/github-gh-skill/reference.md

gh 参考手册（渐进披露）

主说明见 SKILL.md。此处补充常用命令与非交互参数。

全局

用途	示例
帮助	gh <command> --help
指定仓库	-R owner/repo 或在仓库目录执行
JSON 输出	--json field1,field2
jq 过滤	--jq 'select(.state=="OPEN")'

auth

gh auth status
gh auth login
gh auth token

repo

gh repo view --json name,owner,url,description
gh repo clone owner/name
gh repo create name --public --source=. --remote=origin --push

issue

gh issue list --state open --limit 50
gh issue list --json number,title,labels,assignees
gh issue view 123 --json body,author,comments
gh issue create --title "t" --body "b" --label bug
gh issue close 123

pr

gh pr list --state open
gh pr view 42 --json title,body,commits,files
gh pr checkout 42
gh pr diff 42
gh pr merge 42 --squash --delete-branch

合并时若需避免编辑器：使用 --title/--body 与明确的合并策略标志。

workflow / run

gh workflow list
gh run list --workflow "ci.yml" --limit 10
gh run view <run-id>
gh run watch <run-id>
gh run rerun <run-id>

release

gh release list
gh release view v1.2.3
gh release create v1.2.3 ./dist/*.zip --notes "..."

api

# GET
gh api user

# 带查询参数
gh api repos/{owner}/{repo}/pulls --paginate

# POST（示例）
gh api repos/{owner}/{repo}/issues -f title="x" -f body="y"

GraphQL 使用 gh api graphql -f query='...'（复杂查询优先查 GitHub 文档）。

JSON 字段提示

不同子命令可用字段以 gh <cmd> list --json 的帮助为准。常见：

• gh pr list --json: number,title,state,headRefName,baseRefName,author,url
• gh issue list --json: number,title,state,labels,assignees,author

CI 环境变量

• GH_TOKEN：非交互调用时常用（注意最小权限原则）。
• 具体行为以当前 gh 版本文档为准。