用途:当用户询问某个 PR 的 CI 状态或检查结果、需要在合并前监控构建/测试、或等待检查完成时使用。
主要能力:查看检查状态、持续监视直到完成、仅查看必需检查、输出 JSON 供脚本处理、在浏览器中打开。
使用前需确认:PR 编号、URL 或分支名(或当前分支 PR);是否需要监视等待完成;若非当前仓库需指定 --repo OWNER/REPO。
常用命令: 验证认证:gh --version、gh auth status 查看状态:gh pr checks 123 或 gh pr checks 监视完成:gh pr checks 123 --watch、gh pr checks 123 --watch --fail-fast JSON 输出:gh pr checks 123 --json name,state,conclusion 仅必需检查:gh pr checks 123 --required 浏览器查看:gh pr checks 123 --web
常用标志:--watch 监视至结束;--fail-fast 首次失败即退出监视;-i/--interval 刷新间隔秒数(默认 10);--required 仅显示必需检查;--json 输出 JSON(字段含 bucket、name、state 等);-w/--web 在浏览器打开。
退出码:0 全部通过;1 发生错误;8 检查仍待定。
限制与说明:bucket 字段将状态归类为 pass、fail、pending、skipping、cancel;--required 用于聚焦阻塞性检查;--watch 适合在 CI 脚本中等待依赖检查。参考 GitHub CLI 手册 https://cli.github.com/manual/ 及 gh pr checks --help。