github-cli

GitHub CLI 技能

介绍使用 gh CLI 在终端中直接与 GitHub 仓库、服务和 API 交互的模式。涵盖身份验证、仓库管理、议题、拉取请求、Actions、发布、项目、搜索以及 REST/GraphQL API。Git 工作流模式（分支、提交、CI/CD）由单独的技能负责。

快速参考

领域	主要命令
身份验证	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

常见工作流

工作流	命令
快速创建 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
同步 fork	运行 gh repo sync，从上游更新 fork

输出格式

大多数 gh 列表和查看命令都支持结构化输出，便于编写脚本和自动化。

标志	用途
--json	将指定字段输出为 JSON
--jq	使用 jq 表达式筛选 JSON
-t	使用 Go 模板格式化 JSON
--web	在浏览器中打开资源
--comments	包含评论（议题和 PR）

作用范围：仓库、环境、组织

密钥和变量可以设定不同的作用范围。

作用范围	标志示例
仓库	gh secret set KEY（默认）
环境	gh secret set KEY --env production
组织	gh secret set KEY --org name --visibility

项目命令始终需要 --owner @me 或 --owner org-name。

身份验证前提条件

大多数命令需要先通过身份验证才能使用 gh CLI。运行 gh auth status 检查当前会话。缺少权限范围会导致操作静默失败——使用 gh auth refresh -s scope 添加权限范围，无需重新进行身份验证。在 CI 环境中，请设置 GITHUB_TOKEN 或 GH_TOKEN 环境变量，而不是交互式登录。

常见错误

错误	正确做法
未先推送分支就运行 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，根据提交自动填充标题和正文
在 GraphQL 更适合处理嵌套数据时使用 REST API	对需要在一次调用中查询相关对象的请求，使用 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

委派

• 跨仓库搜索代码模式或议题：使用 Explore Agent 和 gh search code、gh search issues
• 自动化多步骤发布工作流：使用 Task Agent 协调创建分支、合并 PR 和发布版本
• 规划仓库结构和访问控制：使用 Plan Agent 设计团队权限、分支保护和工作流架构

参考

• 仓库与身份验证 -- 身份验证、仓库管理、配置、扩展、别名
• 议题 -- 议题的增删改查、标签、分配、置顶、转移、开发分支
• 拉取请求 -- PR 创建、评审、合并、检出、检查、差异、自动合并
• Actions -- 工作流运行、手动触发、机密、变量、缓存、构件下载
• 发布与搜索 -- 发布、证明验证、搜索、gist、SSH/GPG 密钥
• 项目与 API -- Projects v2 管理、REST API、GraphQL API、规则集、状态