macOS 下载、安装 GitHub CLI，把拉取请求、议题与 Actions 带进终端（附安装包gh_2.101.0_macOS_universal.pkg）

1. GitHub CLI 简介

GitHub CLI（命令名 gh）是 GitHub 官方推出的命令行工具，用 Go 语言编写，仓库创建于 2019 年 10 月，2020 年 2 月公开发布测试版，2020 年 9 月发布 1.0 正式版。在它出现之前，社区长期维护着一款非官方的 GitHub 命令行工具 hub；GitHub CLI 是官方以全新设计打造的"正统续作"——hub 的定位是 git 的代理，而 GitHub CLI 是一个独立工具，与 git 并肩工作。目前 GitHub CLI 在 GitHub 上已获得约 4.6 万颗星标、9 千余次派生，支持 GitHub.com、GitHub Enterprise Cloud 与受支持的 GitHub Enterprise Server 版本，覆盖 macOS、Windows 与 Linux 三大平台。

它的核心理念是把 GitHub 带进终端：拉取请求（pull request）、议题（issue）、工作流（workflow）等日常协作操作不必离开命令行就能完成——你在用 git 和代码工作的地方，顺手就能把 GitHub 上的流程跑通。

GitHub CLI 的核心特点：

• 拉取请求全流程：创建、检出、审查、合并 PR，直接在终端查看改动与 CI 状态
• 议题管理：列出、创建、查看、关闭议题，支持标签（label）与里程碑（milestone）筛选
• GitHub Actions 集成：查看运行记录、实时跟踪进度、筛选失败日志、手动触发工作流
• 仓库操作：克隆、创建、派生（fork）、浏览仓库
• API 直达：gh api 一条命令调用 GitHub REST 与 GraphQL API
• 扩展与别名：安装社区扩展、自定义命令别名，还能为编码智能体（coding agent）安装官方 agent skill
• 供应链安全：发布产物附带构建来源证明（Build Provenance Attestation），可用 gh at verify 校验

2. v2.101.0 版本亮点

该版本汇集了 8 位贡献者 的 42 条 贡献。

2.1 认证码自动复制到剪贴板

gh auth login 与 gh auth refresh 现在默认把 OAuth 设备码（device code）复制到剪贴板，省去认证过程中手动复制的一步。如需永久关闭该行为，运行：

gh config set clipboard disabled

单次调用时，显式指定的剪贴板选项仍然优先生效。

2.2 缺陷修复精选

• 仓库克隆改用 API 返回的 SSH URL
• 交互式创建仓库时校验仓库名称的合法性
• 遥测数据在调用结束时落盘，不再丢失
• 将 gh 自身的路径传递给扩展程序
• 修复仓库所有者大小写不一致时删除远程分支失败的问题
• 退役多账户迁移逻辑，简化多账户场景

2.3 Linux 软件仓库 PGP 签名密钥轮换（macOS 用户不受影响）

GitHub CLI 的 APT 与 RPM 软件仓库，以及各个独立的 RPM 包，自本版本起仅使用新的 PGP 密钥签名（指纹 7F38BBB59D064DBCB3D84D725612B36462313325）。在 2026 年 4 月 8 日之前通过官方 APT 或 RPM 仓库安装 gh 且尚未刷新密钥环（keyring）的 Linux 用户，可能会遇到安装或更新失败，需按官方公告指引检查并更新密钥环。Windows 与 macOS 用户，以及通过 Homebrew、GitHub Releases、其他包管理器或源码方式安装的用户均不受影响。

此外，本版本将 Go 升级到 1.27.1，并包含 13 项依赖升级。

3. 获取安装包

如果访问 GitHub 不便，安装包及中文文档：https://hanshuixin.org/go/226F（内含 gh_2.101.0_macOS_universal.pkg、README 中英对照、发布说明中英对照、LICENSE 和源码）。

适用于 macOS arm64（Apple Silicon）与 amd64（Intel）。

GitHub CLI 其他版本：https://hanshuixin.org/resource/software_integrated_package/macOS/GitHub%20CLI

macOS安装cli-v2.101.0（gh_2.101.0_macOS_universal）.zip
├── gh_2.101.0_macOS_universal.pkg   ← 双击运行即可安装
├── macOS安装cli-v2.101.0（gh_2.101.0_macOS_universal）.pdf
├── README/
│   ├── README.md
│   └── README-中文版.md
├── 发布说明/
│   ├── RELEASE-NOTES.md
│   └── RELEASE-NOTES-中文版.md
├── 源码/
│   └── cli-v2.101.0.zip
└── LICENSE

4. 安装

gh_2.101.0_macOS_universal.pkg 是 GitHub CLI 官方发布的 macOS 安装器（pkg 格式），双击运行，按安装向导点击"继续"即可完成安装。安装器会把 gh 放入 /usr/local/bin/gh，该目录默认就在 PATH 中，无需手动配置环境变量。

安装完成后打开"终端"，运行以下命令确认：

gh --version

4.1 登录认证（首次使用必读）

GitHub CLI 的绝大多数功能需要登录 GitHub 账户后才能使用。首次使用时运行：

gh auth login

按交互提示依次选择：账户所在平台（GitHub.com 或企业版）→ 首选协议（HTTPS）→ 认证方式（推荐"Login with a web browser"）。v2.101.0 起设备码会自动复制到剪贴板，在浏览器中粘贴即可完成认证。认证状态可随时用 gh auth status 查看。

5. 使用

5.1 仓库操作

# 克隆仓库
gh repo clone owner/repo

# 用默认浏览器打开仓库页面
gh repo view owner/repo --web

# 创建新仓库（--public / --private / --internal）
gh repo create my-project --public --clone

# 派生（fork）仓库并克隆到本地
gh repo fork owner/repo --clone

5.2 拉取请求（Pull Request）

# 查看当前仓库的 PR 状态（你创建的 / 待你审查的）
gh pr status

# 从当前分支创建 PR
gh pr create --title "feat: 新功能" --body "描述"

# 检出他人的 PR 到本地分支
gh pr checkout 123

# 查看 PR 的 CI 检查结果
gh pr checks

# 合并 PR（--merge / --squash / --rebase）
gh pr merge 123 --squash

5.3 议题（Issue）

# 列出 open 状态的议题
gh issue list

# 创建议题
gh issue create --title "标题" --body "描述"

# 查看议题详情
gh issue view 42

5.4 GitHub Actions 工作流

# 列出最近的工作流运行
gh run list

# 实时跟踪某次运行
gh run watch

# 查看失败步骤的日志（排查利器）
gh run view --log-failed

# 手动触发工作流
gh workflow run build.yml

5.5 API、扩展与别名

# 直接调用 REST API
gh api repos/owner/repo/releases/latest

# GraphQL 查询
gh api graphql -f query='{ viewer { login } }'

# 安装社区扩展
gh extension install owner/gh-extension

# 设置命令别名
gh alias set co 'pr checkout'

GitHub CLI 还内置了面向编码智能体的 agent skill，运行 gh skill install cli/cli gh --scope user 即可安装，让 Claude Code 等智能体直接驱动 gh 完成仓库、PR 与议题操作；gh 发布新版本后用 gh skill update gh 更新。