Back to Details

github

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Use the 
gh
CLI for everything. The user's OAuth access token is exported as 
$GH_TOKEN
; 
gh
reads it automatically — 
gh auth status
will say "not logged in" because gh keeps no config file in the sandbox, but every authenticated subcommand works regardless.
gh --help
and 
gh <subcommand> --help
are always current. When unsure, read the help first instead of guessing flags.
所有操作都使用
gh
CLI完成。用户的OAuth访问令牌会导出为
$GH_TOKEN
；
gh
会自动读取该令牌——
gh auth status
会显示“未登录”，因为gh在沙箱中不保存配置文件，但所有需要认证的子命令仍可正常工作。
gh --help
和
gh <subcommand> --help
始终是最新的。不确定时，请先查看帮助信息，不要猜测参数。

Two ways to call gh — prefer subcommands

两种调用gh的方式——优先使用子命令

Style A: First-class subcommands — START HERE

方式A：一级子命令——从这里开始

gh issue
, 
gh pr
, 
gh repo
, 
gh search
, 
gh release
, 
gh workflow
, 
gh run
, 
gh status
, 
gh project
, 
gh label
, 
gh secret
, 
gh variable
, 
gh gist
. Use these whenever they cover the task; they output formatted text by default and structured JSON via 
--json <fields> [--jq <expr>]
.
gh issue
、
gh pr
、
gh repo
、
gh search
、
gh release
、
gh workflow
、
gh run
、
gh status
、
gh project
、
gh label
、
gh secret
、
gh variable
、
gh gist
。只要这些子命令能覆盖任务需求，就优先使用它们；它们默认输出格式化文本，通过
--json <fields> [--jq <expr>]
可输出结构化JSON。

Style B: Raw REST / GraphQL via 
gh api

方式B：通过
gh api
调用原生REST / GraphQL

gh api <endpoint>
for REST, 
gh api graphql -f query='…'
for GraphQL. Useful when no first-class subcommand exists. Notable flags:
  • -X POST|PATCH|PUT|DELETE
    — override method (default 
    GET
    , becomes 
    POST
    automatically when 
    -f
    /
    -F
    is set).
  • -f key=value
    — string field; 
    -F key=value
    — JSON-typed field (
    true
    /
    123
    /
    @file.json
    ); both URL-encode for 
    GET
    and JSON-encode for body methods.
  • -q '<jq>'
    — same as 
    --jq
    . With a primitive top-level value (string / number) it prints the raw value (no quotes).
  • -H 'Accept: application/vnd.github.raw'
    — fetch a file's raw bytes instead of the JSON wrapper.
  • --paginate
    — auto-walk 
    Link: rel="next"
    .
使用
gh api <endpoint>
调用REST接口，使用
gh api graphql -f query='…'
调用GraphQL接口。当没有对应的一级子命令时，这种方式非常有用。常用参数：
  • -X POST|PATCH|PUT|DELETE
    —— 覆盖请求方法（默认是
    GET
    ，当设置
    -f
    /
    -F
    时会自动变为
    POST
    ）。
  • -f key=value
    —— 字符串字段；
    -F key=value
    —— JSON类型字段（
    true
    /
    123
    /
    @file.json
    ）；对于
    GET
    请求，两者都会进行URL编码；对于请求体方法，都会进行JSON编码。
  • -q '<jq>'
    —— 与
    --jq
    功能相同。如果是顶层原始值（字符串/数字），会直接打印原始值（不带引号）。
  • -H 'Accept: application/vnd.github.raw'
    —— 获取文件的原始字节数据，而非JSON包装格式。
  • --paginate
    —— 自动遍历
    Link: rel="next"
    链接进行分页。

Recipes

操作示例

Triage what's on my plate (issues + PRs + reviews + mentions)

查看我的待处理事项（issues + PRs + 评审 + 提及）

sh
gh status
sh
gh status

List recent issues in a repo

列出仓库中最近的issues

sh
gh issue list --repo OWNER/REPO --limit 20
gh issue list --repo OWNER/REPO --state all --limit 20 \
  --json number,title,state,author,updatedAt,labels --jq '.[]'
sh
gh issue list --repo OWNER/REPO --limit 20
gh issue list --repo OWNER/REPO --state all --limit 20 \
  --json number,title,state,author,updatedAt,labels --jq '.[]'

View an issue with comments

查看包含评论的issue

sh
gh issue view 123 --repo OWNER/REPO --comments
gh issue view 123 --repo OWNER/REPO --json title,body,comments \
  --jq '{title, body, comments: [.comments[] | {author: .author.login, body, createdAt}]}'
sh
gh issue view 123 --repo OWNER/REPO --comments
gh issue view 123 --repo OWNER/REPO --json title,body,comments \
  --jq '{title, body, comments: [.comments[] | {author: .author.login, body, createdAt}]}'

Create / comment / close an issue

创建/评论/关闭issue

sh
gh issue create --repo OWNER/REPO --title "Bug: foo" --body "Repro steps…" --label bug
gh issue comment 123 --repo OWNER/REPO --body "LGTM"
gh issue close 123 --repo OWNER/REPO --comment "Fixed in #456"
sh
gh issue create --repo OWNER/REPO --title "Bug: foo" --body "复现步骤…" --label bug
gh issue comment 123 --repo OWNER/REPO --body "LGTM"
gh issue close 123 --repo OWNER/REPO --comment "已在#456中修复"

List PRs assigned to / authored by me

列出分配给我/由我创建的PRs

sh
gh search prs --assignee=@me --state=open --json number,title,repository,updatedAt
gh search prs --author=@me --state=open
sh
gh search prs --assignee=@me --state=open --json number,title,repository,updatedAt
gh search prs --author=@me --state=open

View a PR with diff and CI checks

查看包含差异和CI检查的PR

sh
gh pr view 456 --repo OWNER/REPO
gh pr diff 456 --repo OWNER/REPO
gh pr checks 456 --repo OWNER/REPO
sh
gh pr view 456 --repo OWNER/REPO
gh pr diff 456 --repo OWNER/REPO
gh pr checks 456 --repo OWNER/REPO

Comment / review / merge a PR

评论/评审/合并PR

sh
gh pr comment 456 --repo OWNER/REPO --body "Please rebase on main."
gh pr review 456 --repo OWNER/REPO --approve --body "LGTM"
gh pr review 456 --repo OWNER/REPO --request-changes --body "See nits"
gh pr merge 456 --repo OWNER/REPO --squash --delete-branch
sh
gh pr comment 456 --repo OWNER/REPO --body "请基于main分支变基。"
gh pr review 456 --repo OWNER/REPO --approve --body "LGTM"
gh pr review 456 --repo OWNER/REPO --request-changes --body "查看细节问题"
gh pr merge 456 --repo OWNER/REPO --squash --delete-branch

Search code across GitHub

在GitHub上搜索代码

sh
gh search code 'someFunction language:typescript' --limit 20 \
  --json repository,path,url --jq '.[] | "\(.repository.nameWithOwner) \(.path)"'
sh
gh search code 'someFunction language:typescript' --limit 20 \
  --json repository,path,url --jq '.[] | "\(.repository.nameWithOwner) \(.path)"'

Read a file from a repo (raw bytes, no base64 dance)

从仓库中读取文件（原始字节，无需base64转换）

sh
gh api "repos/OWNER/REPO/contents/path/to/file.ts" \
  -H 'Accept: application/vnd.github.raw'
sh
gh api "repos/OWNER/REPO/contents/path/to/file.ts" \
  -H 'Accept: application/vnd.github.raw'

List recent commits on the default branch

列出默认分支上最近的提交

sh
gh api "repos/OWNER/REPO/commits?per_page=20" \
  --jq '.[] | "\(.sha[0:7]) \(.commit.author.date) \(.commit.message | split("\n")[0])"'
sh
gh api "repos/OWNER/REPO/commits?per_page=20" \
  --jq '.[] | "\(.sha[0:7]) \(.commit.author.date) \(.commit.message | split("\n")[0])"'

Trigger / inspect Actions workflows

触发/查看Actions工作流

sh
gh workflow list --repo OWNER/REPO
gh workflow run ci.yaml --repo OWNER/REPO --ref main -f key=value
gh run list --repo OWNER/REPO --workflow ci.yaml --limit 5
gh run view <RUN_ID> --repo OWNER/REPO --log-failed
sh
gh workflow list --repo OWNER/REPO
gh workflow run ci.yaml --repo OWNER/REPO --ref main -f key=value
gh run list --repo OWNER/REPO --workflow ci.yaml --limit 5
gh run view <RUN_ID> --repo OWNER/REPO --log-failed

View a repo's metadata

查看仓库的元数据

sh
gh repo view OWNER/REPO
gh repo view OWNER/REPO --json description,url,stargazerCount,defaultBranchRef
sh
gh repo view OWNER/REPO
gh repo view OWNER/REPO --json description,url,stargazerCount,defaultBranchRef

GraphQL for things REST can't do (e.g. project board items)

使用GraphQL完成REST无法实现的操作（例如项目看板项）

sh
gh api graphql -f query='
  query($owner: String!, $repo: String!, $num: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $num) {
        title
        timelineItems(first: 50) {
          nodes { __typename ... on CrossReferencedEvent { source { ... on PullRequest { number title state } } } }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F num=123
sh
gh api graphql -f query='
  query($owner: String!, $repo: String!, $num: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $num) {
        title
        timelineItems(first: 50) {
          nodes { __typename ... on CrossReferencedEvent { source { ... on PullRequest { number title state } } } }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F num=123

Notes

注意事项

  • For private repos the user MUST have granted 
    repo
    scope when they authorized the connection at 
    auth.acedata.cloud/user/connections
    . A 404 on a repo you know exists usually means missing scope, not a wrong URL.
  • When 
    --json
    rejects a field name, gh prints the full list of valid fields — re-read the error and pick from there.
  • gh issue list --search
    and 
    gh search issues
    use the GitHub search syntax (
    is:open
    , 
    assignee:@me
    , 
    repo:owner/name
    , etc.). Use 
    gh search issues
    / 
    gh search prs
    for cross-repo queries; use 
    gh issue list
    for one repo.
  • gh api --paginate
    only works on endpoints that emit a 
    Link
    header; for cursor-paginated endpoints you have to follow 
    pagination.next
    yourself.
  • 对于私有仓库，用户在
    auth.acedata.cloud/user/connections
    授权连接时必须授予
    repo
    权限。如果你确定仓库存在但返回404，通常意味着缺少权限，而非URL错误。
  • 当
    --json
    拒绝某个字段名时，gh会打印所有有效字段列表——请重新阅读错误信息并从中选择。
  • gh issue list --search
    和
    gh search issues
    使用GitHub搜索语法（
    is:open
    、
    assignee:@me
    、
    repo:owner/name
    等）。跨仓库查询使用
    gh search issues
    /
    gh search prs
    ；单仓库查询使用
    gh issue list
    。
  • gh api --paginate
    仅适用于返回
    Link
    头的接口；对于基于游标分页的接口，你需要自行处理
    pagination.next
    。