GitHub CLI 与脚本自动化

文章目录

- 前言
- [一、别把 gh 当成浏览器替身，它更像 GitHub 的终端控制面板](#一、别把 gh 当成浏览器替身，它更像 GitHub 的终端控制面板)
- [二、别名和 JSON 输出才是 gh 真正开始变强的分界线](#二、别名和 JSON 输出才是 gh 真正开始变强的分界线)
- 三、脚本自动化
- 四、认证方式要写对
- 总结

前言

很多开发者真正低估的，不是 GitHub CLI 能不能用，而是它一旦接进日常工作流，会把多少原本分散在浏览器里的动作重新拉回终端。

gh 现在已经覆盖仓库、PR、Issue、Release、Actions、API、变量、密钥等一整套命令域，远不只是一个开 PR 的小工具。它的价值不在于替代网页，而在于把协作操作变成可复用、可脚本化、可批量执行的终端能力。

真正的效率提升，也不只是少点几次鼠标。每次从编辑器切到浏览器，再从浏览器切回终端，都会打断工作流。gh 最值得深入使用的地方，是它把查询、操作、筛选、批处理和自动化串成了一条线。你可以先在终端里看 PR，再直接 checkout，本地跑完测试后提交 review，最后再用同一套命令补标签、发评论、触发 workflow。流程一旦连起来，节奏就会完全不一样。

一、别把 gh 当成浏览器替身，它更像 GitHub 的终端控制面板

很多人第一次接触 gh，最先记住的是 gh pr create、gh pr view、gh issue create 这类命令。这当然没错，但真正该建立的理解是，gh 不是把网页功能简单搬进命令行，而是把 GitHub 上那些本来就很适合自动化的动作，重新组织成了命令接口。

比如 gh repo clone，如果目标仓库本身是一个 fork，它会自动把父仓库加成 upstream 远程，并把上游仓库设成默认远程；这让 fork 场景下的同步操作天然少了一步手工配置。gh repo view 也不只是看 README，它支持 --json 和 --jq，可以直接把仓库当成结构化数据源来查。gh repo list 默认列出 30 个仓库，但可以用 --limit 扩展，再配合 --json 和 --jq 做筛选，这在做仓库资产盘点时非常顺手。

PR 相关命令更能体现这种设计思路。gh pr create 支持 --fill，可以直接从提交信息填充标题和描述，也支持 --draft 创建草稿 PR。gh pr checkout 可以按编号、URL 或分支名直接把 PR 拉到本地。gh run watch 则能在终端里持续观察某次 Actions 运行，必要时还可以加 --exit-status，把 run 的最终结果直接接进脚本判断。你如果只是偶尔用一两条命令，它当然只是方便；可一旦把这些命令接成链路，它就会从一个工具变成你的终端工作面。

二、别名和 JSON 输出才是 gh 真正开始变强的分界线

很多人用 gh 一段时间后，会卡在一个很常见的阶段。命令记住了，常见操作也会了，但还是停留在手工执行层面。真正往前走的一步，是开始用别名和 JSON 输出，把重复动作变成自己的命令体系。

gh 的别名系统并不只是把长命令缩短。gh alias set 支持普通别名，也支持带参数的别名；如果加 --shell，或者让别名以感叹号开头，它还会把整段内容交给 shell 执行。这意味着别名不仅能映射命令，还能直接串管道、做重定向、接多个命令。你完全可以把自己最常用的一组操作收成一套轻量命令层。比如：

bash 复制代码

gh alias set pv 'pr view'
gh alias set bugs 'issue list --label=bug'
gh alias set 'issue mine' 'issue list --mention @me'
gh alias set epicsBy 'issue list --author="$1" --label="epic"'
gh alias set --shell prdiff 'gh pr diff $1 | diff-so-fancy'

这类别名的意义，不只是打字更少，而是它会反过来逼你整理自己的工作模式。哪些命令你反复在用，哪些查询应该固定下来，哪些动作值得组合成一个复用入口，这些在别名层都会逐渐变清楚。gh 官方手册本身也把 issue mine、带 $1 的参数别名、以及 --shell 组合命令作为典型示例，这说明它本来就鼓励你把命令行工作流做成自己的操作层。

JSON 输出则是 gh 从交互工具变成自动化工具的关键。像 gh repo view、gh issue list、gh issue view 这类命令都支持 --json 和 --jq。这意味着你不需要再去解析一堆人类可读的文本，而是可以直接把 GitHub 数据结构化地接进脚本。比如：

bash 复制代码

gh repo view owner/repo --json isPrivate,defaultBranchRef --jq '{private: .isPrivate, branch: .defaultBranchRef.name}'
gh issue list --assignee "@me" --json number,title,updatedAt --jq '.[] | {number, title, updatedAt}'
gh pr list --json number --jq 'length'

一旦你开始这样用，终端里的很多判断逻辑就能直接写出来。仓库是不是私有，当前有没有打开的 PR，我是否被提及在某个 issue 里，这些都不再需要你自己用眼睛扫页面，而是可以进入脚本条件。对脚本化来说，这一步非常关键。

三、脚本自动化

gh 真正适合脚本化的，不是那些极少发生的操作，而是你每天都在重复做、又不值得消耗注意力的动作。比如查自己负责的 issue、拉某个 PR 到本地、批量筛 bug、生成日报、创建 Release、触发某个 workflow，这些都属于高频且规则明确的动作。

这里最稳的思路，不是先上来做复杂平台，而是先从一个最烦的场景开始。比如你经常要统计自己今天做了什么，就完全可以写一个日报脚本，把 PR、Issue 和 review 活动抓出来：

bash 复制代码

#!/usr/bin/env bash

echo "## 今日 GitHub 活动"
echo

echo "### 我创建的 PR"
gh pr list --author "@me" --state all --json number,title,updatedAt,url \
  --jq '.[] | "- PR #\(.number) \(.title) \(.url)"'

echo
echo "### 我创建的 Issue"
gh issue list --author "@me" --state all --json number,title,updatedAt,url \
  --jq '.[] | "- Issue #\(.number) \(.title) \(.url)"'

这种脚本未必复杂，但非常实用。你把原本分散在网页里的查询动作收回来，终端里一条命令就能拿到结果。再往前一步，gh api 会更强。它既能打 REST API，也能访问 GraphQL 端点，还支持 --paginate、--jq、--field 这些参数。像需要跨多个仓库拉统计数据、一次拿多维字段、或者做更复杂的筛选时，gh api 基本就是最顺手的入口。

不过这里有一个边界要说清楚。做批量请求时，别只盯着速度，也要盯着额度。GitHub REST API 的主速率限制里，未认证请求是每小时 60 次，普通认证请求通常是每小时 5000 次；如果是在 GitHub Actions 里用内建 GITHUB_TOKEN，对应的主限制是每个仓库每小时 1000 次，Enterprise Cloud 里的某些场景会更高。也就是说，xargs -P 这类并发处理当然能提速，但一旦脚本要长期跑，就一定要把 rate limit 当成正式约束来设计。

四、认证方式要写对

GitHub-hosted runner 上确实已经预装了 gh，但这不等于你在 workflow 步骤里直接写命令就万事大吉。更稳妥、也更符合官方文档的方式，是在需要使用 gh 的步骤里显式设置 GH_TOKEN，把它指向 ${``{ secrets.GITHUB_TOKEN }}。GitHub 会在每个 job 开始时自动生成 GITHUB_TOKEN，它也能通过 github.token 上下文被 action 访问；但对 gh 来说，官方示例明确推荐的是把这个 token 传给 GH_TOKEN 环境变量。

典型写法像这样：

yaml 复制代码

name: Comment when opened

on:
  issues:
    types: [opened]

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - run: gh issue comment "$ISSUE_URL" --body "Thanks for opening this issue."
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ISSUE_URL: ${{ github.event.issue.html_url }}

这种写法的好处是边界清楚。你知道 gh 在这一小段步骤里能拿到什么权限，也知道 token 来源是什么。如果权限不够，就回到 workflow 的 permissions 去补，而不是模糊地相信 runner 已经帮你处理好了。对于自托管 runner，则更要分清楚两件事，一件是机器上有没有安装 gh，另一件是认证怎么做。你可以用 gh auth login，也可以直接设置 GH_TOKEN 或 GITHUB_TOKEN 环境变量；但不管哪种方式，都应该坚持最小权限原则，不要为了省事给一个权限过大的 PAT。

这也是 gh 在 Actions 里最值得用的场景。像自动给 PR 打标签、按条件评论 issue、根据 workflow_dispatch 触发其他工作流、发布 release，这些本来就属于 GitHub 平台内动作，用 gh 接起来会比自己写 curl 更顺。比如手动或脚本触发 workflow，用 gh workflow run 就能直接完成，只要目标 workflow 支持 workflow_dispatch，还能通过 -f 传输入参数，或者通过标准输入喂 JSON。

总结

GitHub CLI 真正有价值的地方，从来不是让你少开几个网页标签，而是把 GitHub 上原本零散的协作动作重新收编进终端。命令本身只是入口，别名让它更贴近你的习惯，JSON 输出让它能进脚本，gh api 让它能继续往深处扩，Actions 集成则让它从个人工具变成团队自动化的一部分。