GitHub CLI 使用指南：从 issue 到 PR 的命令行工作流

背景

在浏览器和终端之间来回切换处理 GitHub 上的 issue、PR、仓库操作，效率很低。GitHub CLI（gh）是官方提供的命令行工具，可以在终端里完成大部分 GitHub 操作：创建仓库、发起 PR、查看 CI 状态、管理 release 等。适合习惯键盘操作或者需要在服务器没有图形界面时使用。

前置条件：已有一个 GitHub 账号，本地安装了 Git，并且熟悉基本的 Git 操作。如果还没有账号，先去 GitHub 官网 注册。

步骤

1. 安装 gh

Ubuntu/Debian 通过 APT 安装：

1
type -p curl >/dev/null || sudo apt install curl -y
2
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
3
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
4
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
5
sudo apt update
6
sudo apt install gh -y

macOS 用 Homebrew：

1
brew install gh

Windows 可以用 winget、scoop 或直接下载 msi 安装包。安装完成后验证：

1
gh --version

2. 认证

运行登录命令：

1
gh auth login

交互引导中选择 GitHub.com、HTTPS、Login with a web browser，按提示在浏览器输入一次性验证码即可完成 OAuth 认证。如果环境没有图形界面，选择 Paste an authentication token，提前在 GitHub 的 Settings → Developer settings → Personal access tokens 里生成一个 token 粘贴进去。建议使用细粒度 token，仅勾选必要权限，参考 GitHub 文档。

查看登录状态：

1
gh auth status

多账号环境下，gh auth login 会叠加存储，使用 gh auth switch 切换。

3. 创建仓库并推送

本地已有项目代码，不需要在网页上手动建仓库。在项目目录下执行：

1
git init
2
git add .
3
git commit -m "Initial commit"
4
gh repo create my-project --public --source=. --remote=origin --push

参数说明：

• --public 创建公开仓库，--private 为私有仓库
• --source=. 以当前目录作为源
• --remote=origin 自动添加名为 origin 的远程
• --push 创建后立即推送当前分支

更简单的方式是直接运行 gh repo create，选择 “Push an existing local repository to GitHub”，按交互提示填写仓库名和可见性，gh 会自动添加远程并推送。仓库创建后可以用 gh repo view --web 在浏览器打开确认。

4. 克隆仓库

克隆远程仓库，无需复制 URL：

1
gh repo clone owner/repo

在本地仓库目录内，可快速打开 GitHub 页面：

1
gh repo view --web

5. 处理 Issue

列出当前仓库的 issue：

1
gh issue list

创建 issue，标题和正文可以直接在命令行指定：

1
gh issue create --title "修复登录页报错" --body "## 现象\n点击登录按钮后返回 500"

不加参数会弹出交互式表单，可选择模板和 assignees。查看具体 issue：

1
gh issue view 8

从 issue 快速创建关联分支开始开发：

1
gh issue develop 8 --checkout

6. 创建和管理 PR

代码推送到分支后，创建 PR：

1
gh pr create --title "添加用户头像上传功能" --body "实现了头像裁剪和 S3 上传，Closes #8"

--base 可指定目标分支（默认 main）。描述中加入 Closes #8、Fixes #8 等关键字，合并时会自动关闭对应 issue。不加参数运行 gh pr create，标题会自动从 commit 信息提取，并打开编辑器填写详情。

查看 PR 状态和 CI 检查：

1
gh pr status
2
gh pr checks

审查 PR 时，可以直接拉取到本地：

1
gh pr checkout 42

进行代码审查并给出结论：

1
gh pr review 42 --approve
2
# 或 --request-changes

合并 PR：

1
gh pr merge 42 --squash

更多命令参考 GitHub CLI 手册 - pr。

7. 使用 Gist

创建公开或私有 gist：

1
gh gist create script.sh -d "一个部署脚本"

列出自己的 gist：

1
gh gist list

编辑 gist 需要先 clone 到本地，修改后 push，与普通 Git 仓库一样。

8. 查看 Actions 和工作流

在仓库目录中运行：

1
gh run list
2
gh run view <run-id>

查看失败任务的日志，定位错误行：

1
gh run view --log <run-id>

重新运行失败任务：

1
gh run rerun <run-id>

9. 管理 Release

创建 release：

1
gh release create v1.2.0 --title "v1.2.0" --notes "修复了若干 Bug"

使用 GitHub 自动生成的 release notes：

1
gh release create v1.2.0 --generate-notes

上传附加文件：

1
gh release upload v1.2.0 ./build/app.zip

常见问题

1. gh auth login 后弹出浏览器失败（SSH 环境）

在无图形界面的 SSH 会话中，浏览器无法自动打开。选用 token 认证方式，在 GitHub 网页生成 token 后粘贴。生成 token 时注意设置合适的权限范围，建议仅勾选 repo、read:org 等必要项。

2. 提示 “To get started with GitHub CLI, please run: gh auth login”

未认证或认证过期。重新运行 gh auth login。如果使用 token，检查是否已过期，以及权限是否足够。

3. gh pr create 报错 “No pull requests found for branch …”

当前分支还没有推送到远程。先执行 git push -u origin branch-name，再运行 gh pr create。同时确认分支是否基于 main 或 master，并且本地已提交。

4. 某些命令输出中文乱码（Windows 终端）

gh 默认使用 UTF-8 输出。在 Windows 终端中，可以将代码页切换为 65001：chcp 65001，或修改终端字体支持。也可以设置环境变量 GH_FORCE_TTY=1 强制交互模式，参考 GitHub CLI 配置文档。

5. 如何在 CI 环境中使用 gh

在 GitHub Actions 中，gh 已预装并自动认证当前仓库，无需额外登录。在其他 CI 系统中，设置环境变量 GITHUB_TOKEN 为有效 token 即可。GitHub Actions 示例：

1
- name: Create Release
2
  run: gh release create v1.0.0 --generate-notes
3
  env:
4
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

6. 用 gh repo create 创建仓库后远程未添加

交互式创建时如果忘记选择添加远程，或者使用了 --source 但未指定 --remote，会导致本地没有 origin。可以手动添加：

1
git remote add origin https://github.com/owner/repo.git
2
git push -u origin main

总结

gh 把 GitHub 操作从浏览器迁回命令行，覆盖了创建仓库、处理 issue、发起 PR、查看 CI、管理 release 等高频场景。认证一次后，后续操作不需要反复登录，配合 shell 脚本还可以实现自动化，比如在 tag 推送时自动创建 release。

对于习惯 Git 工作流的开发者，gh 是终端里的自然延伸。至少把 gh pr create 和 gh run view 放进日常习惯，长期效率提升明显。