cli-gh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub CLI (gh)

Overview

概述

Expert guidance for GitHub CLI (gh) operations and workflows. Use this skill for command-line GitHub operations including pull request management, issue tracking, repository operations, workflow automation, and codespace management.

Key capabilities:

Create and manage pull requests from the terminal
Track and organize issues efficiently
Search across all of GitHub (repos, issues, PRs)
Manage labels and project organization
Trigger and monitor GitHub Actions workflows
Work with codespaces
Automate repository operations and releases

为GitHub CLI (gh)的操作与工作流提供专业指导。此技能适用于各类GitHub命令行操作，包括拉取请求（PR）管理、Issue跟踪、仓库操作、工作流自动化以及Codespaces管理。

核心功能：

从终端创建和管理拉取请求
高效跟踪和整理Issue
搜索全GitHub平台的资源（仓库、Issue、PR）
管理标签和项目组织
触发和监控GitHub Actions工作流
操作Codespaces
自动化仓库操作和版本发布

Safety Rules

安全规则

CRITICAL: This skill NEVER uses destructive gh CLI operations.

This skill focuses exclusively on safe, read-only, or reversible GitHub operations. The following commands are PROHIBITED and must NEVER be used:

Permanently destructive commands:

```
gh repo delete
```
- Repository deletion
```
gh repo archive
```
- Repository archival
```
gh release delete
```
- Release deletion
```
gh release delete-asset
```
- Asset deletion
```
gh run delete
```
- Workflow run deletion
```
gh cache delete
```
- Cache deletion
```
gh secret delete
```
- Secret deletion
```
gh variable delete
```
- Variable deletion
```
gh label delete
```
- Label deletion
```
gh ssh-key delete
```
- SSH key deletion (can lock out users)
```
gh gpg-key delete
```
- GPG key deletion
```
gh codespace delete
```
- Codespace deletion
```
gh extension remove
```
- Extension removal
```
gh gist delete
```
- Gist deletion
Bulk deletion operations using
```
xargs
```
with any destructive commands
Shell commands:
```
rm -rf
```
(except for temporary file cleanup)

Allowed operations:

Creating resources (PRs, issues, releases, labels, repos)
Viewing and listing (status, logs, information, searches)
Updating and editing existing resources
Closing PRs/issues (reversible - can be reopened)
Canceling workflow runs (stops execution without deleting data)
Merging pull requests (after proper review)
Read-only git operations (
```
git status
```
,
```
git log
```
,
```
git diff
```
)

重要提示：本技能绝不会使用具有破坏性的gh CLI命令。

本技能仅专注于安全、只读或可撤销的GitHub操作。以下命令为禁止使用的命令，绝对不能执行：

永久破坏性命令：

```
gh repo delete
```
- 删除仓库
```
gh repo archive
```
- 归档仓库
```
gh release delete
```
- 删除版本发布
```
gh release delete-asset
```
- 删除发布资产
```
gh run delete
```
- 删除工作流运行记录
```
gh cache delete
```
- 删除缓存
```
gh secret delete
```
- 删除密钥
```
gh variable delete
```
- 删除变量
```
gh label delete
```
- 删除标签
```
gh ssh-key delete
```
- 删除SSH密钥（可能导致用户无法登录）
```
gh gpg-key delete
```
- 删除GPG密钥
```
gh codespace delete
```
- 删除Codespaces
```
gh extension remove
```
- 移除扩展
```
gh gist delete
```
- 删除Gist
使用
```
xargs
```
搭配任何破坏性命令的批量删除操作
Shell命令：
```
rm -rf
```
（临时文件清理除外）

允许的操作：

创建资源（PR、Issue、版本发布、标签、仓库）
查看和列出（状态、日志、信息、搜索结果）
更新和编辑现有资源
关闭PR/Issue（可撤销，可重新打开）
取消工作流运行（停止执行但不删除数据）
合并拉取请求（需经过适当审核）
只读Git操作（
```
git status
```
、
```
git log
```
、
```
git diff
```
）

Installation & Setup

安装与配置

bash

undefined

bash

undefined

Login to GitHub

登录GitHub

gh auth login

Check authentication status

检查认证状态

gh auth status

Configure git to use gh as credential helper

配置git使用gh作为凭证助手

gh auth setup-git

undefined

gh auth setup-git

undefined

Pull Requests

拉取请求（PR）

Creating PRs

创建PR

bash

undefined

bash

undefined

Create PR interactively

交互式创建PR

gh pr create

Create PR with title and body

指定标题和内容创建PR

gh pr create --title "Add feature" --body "Description"

Create PR to specific branch

向指定分支创建PR

gh pr create --base main --head feature-branch

Create draft PR

创建草稿PR

gh pr create --draft

Create PR from current branch

基于当前分支创建PR（自动使用提交信息）

gh pr create --fill # Uses commit messages

undefined

gh pr create --fill

undefined

Viewing PRs

查看PR

bash

undefined

bash

undefined

List PRs

列出所有PR

gh pr list

List my PRs

列出当前用户的PR

gh pr list --author @me

View PR details

查看指定PR详情

gh pr view 123

View PR in browser

在浏览器中打开PR

gh pr view 123 --web

View PR diff

查看PR的差异

gh pr diff 123

Check PR status

检查PR状态

gh pr status

undefined

gh pr status

undefined

Managing PRs

管理PR

bash

undefined

bash

undefined

Checkout PR locally

在本地检出指定PR

gh pr checkout 123

Review PR

审核PR

gh pr review 123 --approve gh pr review 123 --comment --body "Looks good!" gh pr review 123 --request-changes --body "Please fix X"

Merge PR

合并PR

gh pr merge 123 gh pr merge 123 --squash gh pr merge 123 --rebase gh pr merge 123 --merge

Close PR

关闭PR

gh pr close 123

Reopen PR

重新打开PR

gh pr reopen 123

Ready draft PR

将草稿PR标记为就绪

gh pr ready 123

Update PR branch with base branch

更新PR分支与基准分支同步

gh pr update-branch 123

undefined

gh pr update-branch 123

undefined

PR Checks

PR检查

bash

undefined

bash

undefined

View PR checks

查看PR的检查状态

gh pr checks 123

Watch PR checks

监控PR的检查过程

gh pr checks 123 --watch

undefined

gh pr checks 123 --watch

undefined

Issues

Issue

Creating Issues

创建Issue

bash

undefined

bash

undefined

Create issue interactively

交互式创建Issue

gh issue create

Create issue with title and body

指定标题和内容创建Issue

gh issue create --title "Bug report" --body "Description"

Create issue with labels

创建带标签的Issue

gh issue create --title "Bug" --label bug,critical

Assign issue

创建指定负责人的Issue

gh issue create --title "Task" --assignee @me

undefined

gh issue create --title "Task" --assignee @me

undefined

Viewing Issues

查看Issue

bash

undefined

bash

undefined

List issues

列出所有Issue

gh issue list

List my issues

列出当前用户负责的Issue

gh issue list --assignee @me

List by label

按标签列出Issue

gh issue list --label bug

View issue details

查看指定Issue详情

gh issue view 456

View in browser

在浏览器中打开Issue

gh issue view 456 --web

undefined

gh issue view 456 --web

undefined

Managing Issues

管理Issue

bash

undefined

bash

undefined

Close issue

关闭Issue

gh issue close 456

Reopen issue

重新打开Issue

gh issue reopen 456

Edit issue

编辑Issue

gh issue edit 456 --title "New title" gh issue edit 456 --add-label bug gh issue edit 456 --add-assignee @user

Comment on issue

在Issue下评论

gh issue comment 456 --body "Update"

Create branch to work on issue

为Issue创建并检出开发分支

gh issue develop 456 --checkout

undefined

gh issue develop 456 --checkout

undefined

Repository Operations

仓库操作

Repository Info

仓库信息

bash

undefined

bash

undefined

View repository

查看当前仓库信息

gh repo view

View in browser

在浏览器中打开仓库

gh repo view --web

Clone repository

克隆仓库

gh repo clone owner/repo

Fork repository

Fork仓库

gh repo fork owner/repo

List repositories

列出指定用户的仓库

gh repo list owner

undefined

gh repo list owner

undefined

Repository Management

仓库管理

bash

undefined

bash

undefined

Create repository

创建公开仓库

gh repo create my-repo --public gh repo create my-repo --private

gh repo create my-repo --public

Sync fork

创建私有仓库

gh repo sync owner/repo

gh repo create my-repo --private

Set default repository

同步Fork的仓库

gh repo set-default

undefined

gh repo sync owner/repo

Search

设置默认仓库

Search across all of GitHub for repositories, issues, and pull requests.

gh repo set-default

undefined

Search Repositories

搜索

bash

undefined

在全GitHub平台搜索仓库、Issue和拉取请求。

Search for repositories

搜索仓库

gh search repos "machine learning" --language=python

bash

undefined

Search with filters

搜索仓库

gh search repos --stars=">1000" --topic=kubernetes

undefined

gh search repos "machine learning" --language=python

Search Issues

带筛选条件搜索仓库

bash

undefined

gh search repos --stars=">1000" --topic=kubernetes

undefined

Search issues across GitHub

搜索Issue

gh search issues "bug" --label=critical --state=open

bash

undefined

Exclude results (note the -- to prevent flag interpretation)

在全GitHub搜索Issue

gh search issues -- "memory leak -label:wontfix"

undefined

gh search issues "bug" --label=critical --state=open

Search Pull Requests

排除指定结果（注意使用--避免标志解析问题）

bash

undefined

gh search issues -- "memory leak -label:wontfix"

undefined

Search PRs

搜索拉取请求

gh search prs --author=@me --state=open

bash

undefined

Search with date filters

搜索PR

gh search prs "refactor" --created=">2024-01-01"

undefined

gh search prs --author=@me --state=open

Labels

按日期筛选搜索PR

Manage repository labels for issue and PR organization.

gh search prs "refactor" --created=">2024-01-01"

undefined

List and View Labels

List all labels in repository

列出和查看标签

gh label list

undefined

bash

undefined

Create and Edit Labels

列出当前仓库的所有标签

bash

undefined

gh label list

undefined

Create new label

创建和编辑标签

gh label create "priority: high" --color FF0000 --description "High priority items"

bash

undefined

Edit existing label

创建新标签

gh label edit "bug" --color FFAA00 --description "Something isn't working"

undefined

gh label create "priority: high" --color FF0000 --description "High priority items"

Clone Labels Between Repos

编辑现有标签

bash

undefined

gh label edit "bug" --color FFAA00 --description "Something isn't working"

undefined

Clone labels from another repository

在仓库间克隆标签

gh label clone owner/source-repo

undefined

bash

undefined

Codespaces

从其他仓库克隆标签

Manage GitHub Codespaces directly from the terminal.

gh label clone owner/source-repo

undefined

List and Create Codespaces

Codespaces

bash

undefined

直接通过终端管理GitHub Codespaces。

List codespaces

列出和创建Codespaces

gh codespace list

bash

undefined

Create new codespace

列出所有Codespaces

gh codespace create --repo owner/repo

undefined

gh codespace list

Connect to Codespaces

创建新的Codespaces

bash

undefined

gh codespace create --repo owner/repo

undefined

SSH into codespace

连接到Codespaces

gh codespace ssh

bash

undefined

Open in VS Code

通过SSH连接到Codespaces

gh codespace code

gh codespace ssh

Open in JupyterLab

在VS Code中打开Codespaces

gh codespace jupyter

undefined

gh codespace code

Manage Codespace Files

在JupyterLab中打开Codespaces

bash

undefined

gh codespace jupyter

undefined

Copy files to/from codespace

管理Codespaces文件

gh codespace cp local-file.txt remote:~~/path/ gh codespace cp remote:~~/path/file.txt ./local-dir/

bash

undefined

View logs

在本地和Codespaces间复制文件

gh codespace logs

undefined

gh codespace cp local-file.txt remote:~~/path/ gh codespace cp remote:~~/path/file.txt ./local-dir/

Releases

查看Codespaces日志

Creating Releases

—

bash

undefined

gh codespace logs

undefined

Create release

版本发布

—

创建版本发布

gh release create v1.0.0

bash

undefined

Create release with notes

创建版本发布

gh release create v1.0.0 --notes "Release notes"

gh release create v1.0.0

Create release with files

带发布说明创建版本

gh release create v1.0.0 dist/*.tar.gz

gh release create v1.0.0 --notes "Release notes"

Create draft release

带文件创建版本发布

gh release create v1.0.0 --draft

gh release create v1.0.0 dist/*.tar.gz

Generate release notes automatically

创建草稿版本发布

gh release create v1.0.0 --generate-notes

undefined

gh release create v1.0.0 --draft

Managing Releases

自动生成发布说明

bash

undefined

gh release create v1.0.0 --generate-notes

undefined

List releases

管理版本发布

gh release list

bash

undefined

View release

列出所有版本发布

gh release view v1.0.0

gh release list

Download release assets

查看指定版本发布详情

gh release download v1.0.0

undefined

gh release view v1.0.0

Gists

下载版本发布资产

bash

undefined

gh release download v1.0.0

undefined

Create gist

Gist

gh gist create file.txt

bash

undefined

Create gist from stdin

创建Gist

echo "content" | gh gist create -

gh gist create file.txt

List gists

从标准输入创建Gist

gh gist list

echo "content" | gh gist create -

View gist

列出所有Gist

gh gist view <gist-id>

gh gist list

Edit gist

查看指定Gist

gh gist edit <gist-id>

undefined

gh gist view <gist-id>

Configuration

编辑指定Gist

bash

undefined

gh gist edit <gist-id>

undefined

Set default editor

配置

gh config set editor vim

bash

undefined

Set default git protocol

设置默认编辑器

gh config set git_protocol ssh

gh config set editor vim

View configuration

设置默认Git协议

gh config list

gh config set git_protocol ssh

Set browser

查看当前配置

gh config set browser firefox

undefined

gh config list

Quick Reference

设置默认浏览器

Common gh operations at a glance:

Operation	Command	Common Flags
Create PR	`gh pr create`	`--draft` , `--fill` , `--base` , `--title`
List PRs	`gh pr list`	`--author @me` , `--label` , `--state`
View PR	`gh pr view <number>`	`--web` , `--comments`
Merge PR	`gh pr merge <number>`	`--squash` , `--rebase` , `--delete-branch`
Create issue	`gh issue create`	`--title` , `--body` , `--label`
List issues	`gh issue list`	`--assignee @me` , `--label` , `--state`
View issue	`gh issue view <number>`	`--web` , `--comments`
Clone repo	`gh repo clone <repo>`	`--` (to pass git flags)
Fork repo	`gh repo fork`	`--clone` , `--remote`
View repo	`gh repo view`	`--web`
Create release	`gh release create <tag>`	`--title` , `--notes` , `--draft`
Run workflow	`gh workflow run <name>`	`--ref` , `--field`
Watch run	`gh run watch <id>`	`--exit-status`
Search repos	`gh search repos <query>`	`--language` , `--stars`
Create label	`gh label create <name>`	`--color` , `--description`
Create codespace	`gh codespace create`	`--repo` , `--branch`
SSH to codespace	`gh codespace ssh`	`--codespace`

gh config set browser firefox

undefined

Additional Resources

快速参考

Reference Guides

—

For detailed patterns and advanced usage, see:

Workflows & Actions - GitHub Actions workflows, runs, cache management, and CI/CD integration patterns
Advanced Features - Aliases, API access, extensions, secrets, SSH/GPG keys, organizations, projects, and advanced scripting
Automation Workflows - Common automation patterns, daily reports, release automation, and team collaboration workflows
Troubleshooting - Solutions for authentication, permissions, rate limiting, and common errors

常用gh操作速览：

操作	命令	常用参数
创建PR	`gh pr create`	`--draft` , `--fill` , `--base` , `--title`
列出PR	`gh pr list`	`--author @me` , `--label` , `--state`
查看PR	`gh pr view <number>`	`--web` , `--comments`
合并PR	`gh pr merge <number>`	`--squash` , `--rebase` , `--delete-branch`
创建Issue	`gh issue create`	`--title` , `--body` , `--label`
列出Issue	`gh issue list`	`--assignee @me` , `--label` , `--state`
查看Issue	`gh issue view <number>`	`--web` , `--comments`
克隆仓库	`gh repo clone <repo>`	`--` （传递Git参数）
Fork仓库	`gh repo fork`	`--clone` , `--remote`
查看仓库	`gh repo view`	`--web`
创建版本发布	`gh release create <tag>`	`--title` , `--notes` , `--draft`
运行工作流	`gh workflow run <name>`	`--ref` , `--field`
监控工作流运行	`gh run watch <id>`	`--exit-status`
搜索仓库	`gh search repos <query>`	`--language` , `--stars`
创建标签	`gh label create <name>`	`--color` , `--description`
创建Codespace	`gh codespace create`	`--repo` , `--branch`
SSH连接Codespace	`gh codespace ssh`	`--codespace`

Example Scripts

额外资源

—

参考指南

Practical automation scripts (see

examples/

directory):

```
auto-pr-create.sh
```
- Automated PR creation workflow
```
issue-triage.sh
```
- Bulk issue labeling and assignment
```
workflow-monitor.sh
```
- Watch and notify on workflow completion
```
release-automation.sh
```
- Complete release workflow automation

如需详细模式和高级用法，请查看：

工作流与Actions - GitHub Actions工作流、运行记录、缓存管理及CI/CD集成模式
高级功能 - 别名、API访问、扩展、密钥、SSH/GPG密钥、组织、项目及高级脚本
自动化工作流 - 常见自动化模式、日报、发布自动化及团队协作工作流
故障排除 - 认证、权限、速率限制及常见错误的解决方案

External Documentation

示例脚本

Official Manual: https://cli.github.com/manual
GitHub Community: https://github.com/cli/cli/discussions
API Documentation: https://docs.github.com/en/rest
Extension Marketplace: https://github.com/topics/gh-extension

实用自动化脚本（查看

examples/

目录）：

```
auto-pr-create.sh
```
- 自动化PR创建工作流
```
issue-triage.sh
```
- 批量Issue标签分配
```
workflow-monitor.sh
```
- 监控工作流完成并通知
```
release-automation.sh
```
- 完整的发布工作流自动化

JSON Output

外部文档

Use

--json

flag for structured output. Always verify field names with
--help
as they differ from GitHub API names.

bash

undefined

官方手册：https://cli.github.com/manual
GitHub社区：https://github.com/cli/cli/discussions
API文档：https://docs.github.com/en/rest
扩展市场：https://github.com/topics/gh-extension

Check available JSON fields for any command

JSON输出

gh repo view --help | grep -A 50 "JSON FIELDS" gh pr list --help | grep -A 50 "JSON FIELDS"

undefined

使用

--json

参数获取结构化输出。请始终通过
--help
验证字段名称，因为它们与GitHub API的字段名称不同。

bash

undefined

Common JSON Field Corrections

查看任意命令支持的JSON字段

Wrong (API-style)	Correct (gh CLI)
`stargazersCount`	`stargazerCount`
`forksCount`	`forkCount`
`watchersCount`	`watchers`
`openIssuesCount`	`issues`

gh repo view --help | grep -A 50 "JSON FIELDS" gh pr list --help | grep -A 50 "JSON FIELDS"

undefined

Repository View Fields

常见JSON字段修正

bash

undefined

错误（API风格）	正确（gh CLI）
`stargazersCount`	`stargazerCount`
`forksCount`	`forkCount`
`watchersCount`	`watchers`
`openIssuesCount`	`issues`

Common fields for gh repo view --json

仓库查看字段

gh repo view owner/repo --json name,description,stargazerCount,forkCount,updatedAt,url,readme

undefined

bash

undefined

Tips

gh repo view --json常用字段

Use
```
--web
```
flag to open items in browser for detailed view
Leverage interactive prompts by omitting parameters - most commands support interactive mode
Apply filters with
```
--author
```
,
```
--label
```
,
```
--state
```
to narrow down lists efficiently
Add
```
--json
```
flag to enable scriptable output for automation
Always check
--help
for valid JSON field names - they differ from GitHub API
Use
```
gh repo create --template
```
to scaffold from template repositories
Enable auto-merge with
```
gh pr merge --auto
```
for PRs that pass checks

gh repo view owner/repo --json name,description,stargazerCount,forkCount,updatedAt,url,readme

undefined

—

小贴士

—

使用
```
--web
```
参数在浏览器中打开项目以查看详细信息
省略参数以使用交互式提示 - 大多数命令支持交互式模式
使用
```
--author
```
、
```
--label
```
、
```
--state
```
等筛选器高效缩小列表范围
添加
```
--json
```
参数以支持脚本化输出，实现自动化
始终通过
--help
确认有效的JSON字段名称 - 它们与GitHub API不同
使用
```
gh repo create --template
```
从模板仓库搭建项目
对通过检查的PR使用
```
gh pr merge --auto
```
启用自动合并