Back to Details

github-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub CLI Skill

GitHub CLI Skill

Provides patterns for the 
gh
CLI to interact with GitHub repositories, services, and APIs directly from the terminal. Covers authentication, repository management, issues, pull requests, actions, releases, projects, search, and the REST/GraphQL API. Git workflow patterns (branching, commits, CI/CD) are handled by a separate skill.
提供
gh
CLI的使用范式，可直接在终端中与GitHub仓库、服务及API进行交互。涵盖认证、仓库管理、议题、拉取请求、Actions、版本发布、项目、搜索以及REST/GraphQL API。Git工作流范式（分支、提交、CI/CD）由单独的技能文档处理。

Quick Reference

快速参考

AreaKey Commands
Auth
gh auth status
, 
gh auth login
, 
gh auth token
Repos
gh repo clone
, 
gh repo create
, 
gh repo fork
, 
gh repo sync
Browse
gh browse
, 
gh browse --settings
, 
gh browse file.ts:42
Issues
gh issue list
, 
gh issue create
, 
gh issue edit
, 
gh issue close
Pull Requests
gh pr create
, 
gh pr review
, 
gh pr merge
, 
gh pr checkout
Actions
gh run list
, 
gh run view
, 
gh workflow run
, 
gh cache list
Releases
gh release create
, 
gh release list
, 
gh release verify
Projects
gh project list
, 
gh project create
, 
gh project item-add
Search
gh search repos
, 
gh search issues
, 
gh search code
API
gh api repos/{owner}/{repo}
, 
gh api graphql
Security
gh attestation verify
, 
gh ruleset list
, 
gh secret set
Status
gh status
, 
gh pr checks
, 
gh pr status
Codespaces
gh codespace create
, 
gh codespace ssh
, 
gh codespace code
领域核心命令
认证
gh auth status
, 
gh auth login
, 
gh auth token
仓库
gh repo clone
, 
gh repo create
, 
gh repo fork
, 
gh repo sync
浏览
gh browse
, 
gh browse --settings
, 
gh browse file.ts:42
议题
gh issue list
, 
gh issue create
, 
gh issue edit
, 
gh issue close
拉取请求
gh pr create
, 
gh pr review
, 
gh pr merge
, 
gh pr checkout
Actions
gh run list
, 
gh run view
, 
gh workflow run
, 
gh cache list
版本发布
gh release create
, 
gh release list
, 
gh release verify
项目
gh project list
, 
gh project create
, 
gh project item-add
搜索
gh search repos
, 
gh search issues
, 
gh search code
API
gh api repos/{owner}/{repo}
, 
gh api graphql
安全
gh attestation verify
, 
gh ruleset list
, 
gh secret set
状态
gh status
, 
gh pr checks
, 
gh pr status
Codespaces
gh codespace create
, 
gh codespace ssh
, 
gh codespace code

Common Workflows

常见工作流

WorkflowCommands
Quick PR
git push -u origin feat
then 
gh pr create --fill
Draft PR
gh pr create --draft --fill
then 
gh pr ready
when done
Review and merge
gh pr checkout 45
then 
gh pr review --approve
then 
gh pr merge --squash --delete-branch
Auto-merge PR
gh pr merge --auto --squash
(waits for required checks to pass)
Check CI
gh pr checks
then 
gh run watch
Rerun failed CI
gh run rerun <run-id> --failed
Create release
gh release create v1.0.0 --generate-notes
Search code
gh search code "handleAuth" --repo owner/repo
Add issue to project
gh project item-add 1 --owner @me --url <issue-url>
Verify artifact
gh attestation verify artifact.tar.gz --owner owner
Trigger workflow
gh workflow run deploy.yml -f environment=production
Revert merged PR
gh pr revert 45
Sync fork
gh repo sync
to update fork from upstream
工作流名称命令
快速创建PR
git push -u origin feat
之后执行 
gh pr create --fill
草稿PR
gh pr create --draft --fill
完成后执行 
gh pr ready
评审与合并
gh pr checkout 45
之后执行 
gh pr review --approve
再执行 
gh pr merge --squash --delete-branch
自动合并PR
gh pr merge --auto --squash
（等待必要检查通过）
检查CI状态
gh pr checks
之后执行 
gh run watch
重新运行失败的CI
gh run rerun <run-id> --failed
创建版本发布
gh release create v1.0.0 --generate-notes
搜索代码
gh search code "handleAuth" --repo owner/repo
将议题添加到项目
gh project item-add 1 --owner @me --url <issue-url>
验证工件
gh attestation verify artifact.tar.gz --owner owner
触发工作流
gh workflow run deploy.yml -f environment=production
回滚已合并的PR
gh pr revert 45
同步复刻仓库
gh repo sync
从上游仓库更新复刻版本

Output Formatting

输出格式化

Most 
gh
list and view commands support structured output for scripting and automation.
FlagPurpose
--json
Output specified fields as JSON
--jq
Filter JSON with jq expressions
-t
Format JSON with Go templates
--web
Open the resource in a browser
--comments
Include comments (issues and PRs)
大多数
gh
列表和查看命令支持结构化输出，适用于脚本编写和自动化场景。
参数用途
--json
以JSON格式输出指定字段
--jq
使用jq表达式过滤JSON
-t
使用Go模板格式化JSON
--web
在浏览器中打开资源
--comments
包含评论（议题和PR）

Scoping: Repo, Env, Org

作用域：仓库、环境、组织

Secrets and variables can be scoped to different levels.
ScopeFlag Example
Repository
gh secret set KEY
(default)
Environment
gh secret set KEY --env production
Organization
gh secret set KEY --org name --visibility
Project commands always require 
--owner @me
or 
--owner org-name
.
密钥和变量可作用于不同层级。
作用域参数示例
仓库
gh secret set KEY
（默认）
环境
gh secret set KEY --env production
组织
gh secret set KEY --org name --visibility
项目命令始终需要指定
--owner @me
或
--owner org-name
。

Authentication Prerequisites

认证前提条件

The 
gh
CLI requires authentication before most commands work. Run 
gh auth status
to verify the current session. Missing scopes cause silent failures -- use 
gh auth refresh -s scope
to add scopes without re-authenticating. For CI environments, set the 
GITHUB_TOKEN
or 
GH_TOKEN
environment variable instead of interactive login.
gh
CLI在执行大多数命令前需要完成认证。执行
gh auth status
可验证当前会话状态。缺少权限范围会导致静默失败——使用
gh auth refresh -s scope
可添加权限范围，无需重新认证。对于CI环境，设置
GITHUB_TOKEN
或
GH_TOKEN
环境变量即可，无需交互式登录。

Common Mistakes

常见错误

MistakeCorrect Pattern
Running 
gh pr create
without pushing the branch first		Push with 
git push -u origin branch
before creating a PR
Using 
gh pr merge
without checking CI status		Run 
gh pr checks
first or use 
gh pr merge --auto
to wait for checks
Forgetting 
--fill
when creating PRs from well-written commits		Use 
gh pr create --fill
to auto-populate title and body from commits
Using REST API when GraphQL is more efficient for nested dataUse 
gh api graphql
for queries needing related objects in one call
Not authenticating with correct scopesRun 
gh auth status
to verify scopes, 
gh auth refresh -s scope
to add
Using 
gh project
commands without specifying 
--owner
Always pass 
--owner @me
or 
--owner org-name
for project commands
Manually downloading CI artifactsUse 
gh run download <run-id>
to download artifacts programmatically
Not using 
--json
for scripting		Add 
--json field1,field2
and 
--jq
for machine-readable output
Merging without 
--delete-branch
Use 
gh pr merge --squash --delete-branch
to clean up after merge
Running 
gh api
POST without 
-f
fields		Use 
-f key=value
for string fields, 
-F
for typed fields
错误操作正确操作方式
未推送分支就运行
gh pr create
创建PR前先执行
git push -u origin branch
推送分支
未检查CI状态就执行
gh pr merge
先执行
gh pr checks
检查状态，或使用
gh pr merge --auto
等待检查通过
从规范提交创建PR时忘记使用
--fill
使用
gh pr create --fill
从提交记录自动填充PR标题和内容
处理嵌套数据时使用REST API而不是更高效的GraphQL对于需要在单次调用中获取关联对象的查询，使用
gh api graphql
未使用正确权限范围进行认证执行
gh auth status
验证权限范围，使用
gh auth refresh -s scope
添加权限
执行
gh project
命令时未指定
--owner
项目命令始终需要传递
--owner @me
或
--owner org-name
手动下载CI工件使用
gh run download <run-id>
以编程方式下载工件
编写脚本时未使用
--json
添加
--json field1,field2
和
--jq
参数以获取机器可读输出
合并时未使用
--delete-branch
使用
gh pr merge --squash --delete-branch
在合并后清理分支
执行
gh api
POST请求时未使用
-f
参数		字符串字段使用
-f key=value
，类型字段使用
-F

Delegation

任务委托

  • Search across repositories for code patterns or issues: Use 
    Explore
    agent with 
    gh search code
    and 
    gh search issues
  • Automate multi-step release workflows: Use 
    Task
    agent to coordinate branch creation, PR merge, and release publishing
  • Plan repository structure and access controls: Use 
    Plan
    agent to design team permissions, branch protection, and workflow architecture
  • 跨仓库搜索代码模式或议题：使用
    Explore
    agent配合
    gh search code
    和
    gh search issues
  • 自动化多步骤发布工作流：使用
    Task
    agent协调分支创建、PR合并和版本发布
  • 规划仓库结构和访问控制：使用
    Plan
    agent设计团队权限、分支保护和工作流架构

References

参考资料

  • Repos & Auth -- Authentication, repository management, configuration, extensions, aliases
  • Issues -- Issue CRUD, labels, assignments, pinning, transferring, development branches
  • Pull Requests -- PR creation, review, merge, checkout, checks, diff, auto-merge
  • Actions -- Workflow runs, manual triggers, secrets, variables, caches, artifact downloads
  • Releases & Search -- Releases, attestation verification, search, gists, SSH/GPG keys
  • Projects & API -- Projects v2 management, REST API, GraphQL API, rulesets, status
  • 仓库与认证 -- 认证、仓库管理、配置、扩展、别名
  • 议题 -- 议题的增删改查、标签、分配、置顶、转移、开发分支
  • 拉取请求 -- PR创建、评审、合并、检出、检查、差异对比、自动合并
  • Actions -- 工作流运行、手动触发、密钥、变量、缓存、工件下载
  • 版本发布与搜索 -- 版本发布、证明验证、搜索、Gist、SSH/GPG密钥
  • 项目与API -- Projects v2管理、REST API、GraphQL API、规则集、状态