GitHub CLI とは、pull request・issue・GitHub Actions などの GitHub の機能を端末から扱える、GitHub 公式のコマンドラインの道具（gh）です。
- gh コマンドで何ができるか、git との違い、この頁で使う gh run view・gh pr edit・gh pr checks・gh api・gh auth token の役目
- gh の出力と終了コードを、そのまま「成功した」の証拠にしてはいけない場面と、REST や読み直しで確かめる手順
- ログが空のまま成功で終わる、gh pr edit が本文を変えない、見張りの loop で API の上限を使い切った、など当社の記録
当社は AIエージェント の席に、PR を立てる・CI を見る・本文を直す、といった GitHub の操作を gh で撃たせています。席は命令の出力と終了コードを文字どおりに読むので、「何も出ずに 0 で終わった」が「問題が無い」に化けました。この頁は gh の公式の文書の定義と、その記録を並べたものです。
GitHub CLI（gh）とは：GitHub 専用、git とは別の道具
公式の文書は、GitHub CLI を「PR・issue・GitHub Actions などを端末に持ってくる道具」と説明し、オープンソースだと書いています。git がどのリポジトリでも使えるのに対して、gh は GitHub と働くための物で、GitHub の操作を script に組みやすくする、とも書いています（about-github-cli の文書・2026-11-08 に確認）。
| 命令 | 何をするか（公式の文書） | 当社が使う場面 |
|---|---|---|
gh pr create | GitHub に PR を作り、できた PR の URL を出す | 席が作業の枝から PR を立てる |
gh pr edit | PR の題（--title）・本文（--body／--body-file）などを変える | PR の本文に結果を書き足す |
gh pr checks | 1 つの PR の CI の状態を出す。--watch で終わるまで見張る | マージしてよいかを見る |
gh run view | workflow の run を見る。--log で全部のログ、--log-failed で失敗した step のログ | 落ちた理由を読む |
gh api | 認証つきで GitHub の API（REST の道か graphql）を撃ち、応答を出す | gh の上の命令が効かない時の撃ち直し |
gh auth token | その host の口座の認証の token を出す | gh 以外の道具で同じ API を撃つ |
出典: GitHub Docs「About GitHub CLI」https://docs.github.com/en/github-cli/github-cli/about-github-cli ・GitHub CLI manual「gh pr create」「gh pr edit」「gh pr checks」「gh run view」「gh api」「gh auth token」（https://cli.github.com/manual/ の各頁・どれも 2026-11-08 に確認）。
下の記録はどれも、gh を撃った席が「終わった」「直った」と報告し、後で別の道から引き直して誤りと分かった物です。当社の記録の頃の gh の版は 2.68.1 でした（社の実測 2026-09-23）。今の版で同じことが起きるかは確かめていません。
gh run view --log が 0 バイトで終了 0：「エラー無し」ではなく経路が効いていない
失敗した run に gh run view --log-failed を撃つと、0 行で終了コード 0 でした。陽性対照として、成功した run に --log を撃っても 0 行でした。ここで「落ちた step が無い」ではなく「ログを引く経路そのものが効いていない」と判定しました（社の実測 2026-09-18）。同じ run を REST の job のログで引くと 37,971 バイト取れ、エラーの行まで読めました（社の実測 2026-09-18）。
| 日 | gh run view のログ | REST の job のログ |
|---|---|---|
| 2026-09-18 | 0 行・終了 0 | 37,971 バイト |
| 2026-09-19 | 0 バイト | 28,448 バイト |
| 2026-09-23 | 0 行 | 239 行 |
| 2026-09-23（別のリポ） | 0 行 | 1,013 行・✘ 2 件 |
出典: 社の実測 2026-09-18・2026-09-19・2026-09-23。
REST の道は gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs です。公式の文書では、この道は平文のログへの 302 の転送を返し、その URL は 1 分で切れます（workflow-jobs の文書・2026-11-08 に確認）。
gh run view の文書には、zip のログと job をうまく結びつけられない時は job ごとに API で取り直す、25 を超える job のログが欠けると命令は失敗する、と書かれています（gh run view の文書・2026-11-08 に確認）。当社が見た「0 行で終了 0」は、この説明とは合いません。版による違いかは確かめていません。
走っている途中の run のログを、終わったログと読まない
当社の席は、まだ走っている run の --log-failed の部分のログを見て「試験は 1 本も落ちていない」と報告しました。実際には落ちていました（社の実測 2026-09-18）。gh run view の文書は、走っている途中の run をどう扱うかを書いていません（2026-11-08 に確認）。
REST の job には status（queued・in_progress・completed など）と、終わった時刻の completed_at が在ります（workflow-jobs の文書・2026-11-08 に確認）。当社は、status が completed になる前にログを読まないことにしました（社の実測 2026-09-18）。
gh run view --job のログが途中で切れて終了 0：末尾の時刻で確かめる
gh run view --job <id> --log が 226,414 行で止まり、その中に FAIL の行は 0 でした。終了コードは 0 でした（社の実測 2026-10-13）。
そこで gh api で job のログを引くと、ESC の文字を含むログだったため「pass --allow-escape-sequences」と言って出力を拒み、ファイルへ落とすと 0 バイトでした（社の実測 2026-10-13）。gh api の文書には --allow-escape-sequences が「端末のエスケープの文字の表示を許す」印として載っていますが、それ以上の説明はありません（gh api の文書・2026-11-08 に確認）。
最後に、gh auth token が出す token を curl に Bearer で渡して同じ REST を引くと 33MB 取れ、落ちた試験のファイル名の FAIL の行が在りました（社の実測 2026-10-13）。
取れたログが全部かは、次の 2 つで確かめます（社の実測 2026-10-13）。
- 既に分かっている PASS の行を数え、ログに在るかを見る
- ログの末尾の時刻が、job の
completed_atに届いているかを見る
落ちた試験を撃ち直す手は flaky test の頁に書いています。
gh pr edit が本文も題も変えずに終わる：引き直して確かめる
gh pr edit --body-file が、PR の本文を 1 文字も変えずに終わったことが 4 日ありました（社の実測 2026-09-18・2026-09-20・2026-09-21・2026-09-25）。出たのは Projects (classic) の廃止を知らせる GraphQL のエラー（projectCards）の 1 行だけで、成功したように見えました。終了コードは 0 だった回（2026-09-18）も 1 だった回（2026-09-21）もあります（社の実測）。gh pr edit の文書は Projects (classic) の廃止にも projectCards にも触れていません（2026-11-08 に確認）。
gh pr edit --title も、題を変えずに終わったことがあります（社の実測 2026-09-20）。
| 変えたい物 | 撃ち直し（REST） | 確かめ方 |
|---|---|---|
| 本文 | gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -F "body=@<ファイル>" | 本文を引き直し、足した語の数か行数を見る（71 行が 81 行になった） |
| 題 | gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f title=<題> | gh pr view --json title で引き直してから「直った」と書く |
出典: 社の実測 2026-09-18（本文・行数）・2026-09-20（題）。
gh api の文書では、-F の値が @ で始まると残りをファイル名として読み、-f は文字のままの値を足します。値を足すと既定の method は POST になるので、-X で PATCH を名指しします（gh api の文書・2026-11-08 に確認）。
gh pr create の直後に CI が 1 本も走らない
gh pr create で PR を作って 4 分たっても、その head の SHA の run が 0 本でした。同じ時刻に他の PR では 3 秒で走っていたので、Actions は生きていました（社の実測 2026-09-21・2026-09-22）。PR を close して reopen すると、reopened の合図で走りました（社の実測 2026-09-21）。gh pr create の文書は CI やチェックに触れていません（2026-11-08 に確認）。
当社は、PR を立てたら必須のチェックが一覧に載っているかを 1 回見ることにしました。走ったかは gh api "repos/<owner>/<repo>/actions/runs?head_sha=<sha>" の total_count で見ます（社の実測 2026-09-22）。
gh pr checks と statusCheckRollup：「無い」「空」を緑と読まない
push の直後に gh pr checks を撃つと、すぐ答える外のチェックだけを見て「完了」を返しました。まだ登録されていないチェックは「無い」と返ります（社の実測 2026-09-25）。gh pr checks の文書は、--required で必須のチェックだけを出す印と、チェックが pending の時の終了コード 8 を載せています（gh pr checks の文書・2026-11-08 に確認）。まだ登録されていないチェックは一覧に出ないので、当社は必須のチェックの名前を名指しして緑を待つか、gh run list --workflow <ファイル> --branch <枝> に run が在るかを見ます。0 本なら「まだ始まっていない」と読みます（社の実測 2026-09-25）。
gh pr view --json statusCheckRollup では、走っている途中のチェックの conclusion は null ではなく空の文字でした。「conclusion が null でない物は終わった」と数えたら、走っている 4 本を失敗と数えかけました。実際の赤は 0 本でした（社の実測 2026-09-24）。
| 見えた物 | 読んではいけない意味 | 当社の読み方 |
|---|---|---|
| gh pr checks が push の直後に完了 | 全部緑 | 必須のチェックを名指しして待つ |
| conclusion が空の文字 | 終わった・失敗 | status が COMPLETED かつ FAILURE／TIMED_OUT／CANCELLED の物だけを赤と数える |
| gh run list --commit <統合の commit> が 0 本 | 緑・走る物が無い | 0 本は「分からない」。別の道で確かめる |
出典: 社の実測 2026-09-24・2026-09-25。
最後の行は、既に本番へ出た commit で撃っても 0 本だった、という陽性対照から決めました（社の実測 2026-09-24）。merge queue での PR の扱いは merge queue と GitHub MCP の頁にあります。
GitHub API の rate limit：見張りの loop が REST の上限を使い切った
公式の文書では、口座の REST の上限は 1 時間 5,000 回で、GraphQL の上限（1 時間 5,000 点）とは別に数えます。上限を超えると 403 か 429 が返り、x-ratelimit-reset の時刻まで撃ち直すな、と書いています。GET /rate_limit を撃っても REST の上限は減りません（REST と GraphQL の rate limit の文書・2026-11-08 に確認）。
2026-10-15、30 前後の席が gh run list・gh api・gh run watch で CI を見張り、REST（core）の残りが 0/5000 になりました。GraphQL は 4,841 残っていました。戻るまで約 20 分かかりました（社の実測 2026-10-15）。上限の間は gh pr checks の表示が pending／fail のまま止まり、それが CI の結果に見えました（社の実測 2026-10-15）。
2026-10-21 にも同じ形を踏みました。1 分おきの見張りを 3 本並べ、20 分の間に見張りが 403 を 20 回返し、本番へ出す段の失敗に気づくのが 20 分遅れました（社の実測 2026-10-21）。
| 決めたこと | 決めた日 |
|---|---|
| CI と PR の状態は GraphQL の gh pr checks／gh pr view --json statusCheckRollup で見る | 2026-10-15 |
| REST を見張りの loop で回さない。間隔は 60 秒以上。gh run watch を同時に何本も走らせない | 2026-10-15 |
| 見張りは GitHub の API を撃たない形（git fetch・5 分おき）にし、gh は判定の 1 回だけ | 2026-10-21 |
残りは gh api rate_limit で見る | 2026-10-21 |
出典: 社の実測 2026-10-15・2026-10-21。/rate_limit が上限を減らさないことは rate-limit の文書による（2026-11-08 に確認）。
CI の分の数え方は GitHub Actions の料金、自前の runner の話は self-hosted runner の頁にあります。
よくある質問
gh コマンドと git コマンドの違いは？
git はどのリポジトリでも使える版の管理の道具で、gh は PR・issue・GitHub Actions など GitHub の機能を扱う専用の道具です（about-github-cli の文書・2026-11-08 に確認）。PR を立てる・CI を見るのは gh、commit や push は git が受け持ちます。
gh run view --log が何も出さずに終わったら、エラーは無かった？
そうとは限りません。当社では、失敗した run でも成功した run でも 0 行・終了 0 になり、REST の job のログで引くと 239 行から 37,971 バイトのログが在りました（社の実測 2026-09-18・2026-09-23）。成功した run で陽性対照を撃ち、0 行なら経路を疑います。
gh pr edit が終了コード 0 で終わったら、本文は変わった？
当社では、projectCards の GraphQL のエラーが 1 行出ただけで、本文が 1 文字も変わらなかった回が 4 日ありました（社の実測 2026-09-18〜2026-09-25）。撃った後に本文を引き直し、変わっていなければ gh api -X PATCH で撃ち直します。
gh auth token は何に使う？
その host の口座の token を出す命令です（gh auth token の文書・2026-11-08 に確認）。当社では、gh api が出力を拒んだ job のログを、この token を curl に渡して同じ REST から 33MB 引きました（社の実測 2026-10-13）。
GitHub API の rate limit の残りはどう見る？
gh api rate_limit で core（REST）と graphql の残りが見え、この道は REST の上限を減らしません（rate-limit の文書・2026-11-08 に確認）。当社は見張りの loop で REST を 0/5000 まで使い切ったので、見張りは API を撃たない形にしました（社の実測 2026-10-15・2026-10-21）。
出典
- GitHub Docs「About GitHub CLI」https://docs.github.com/en/github-cli/github-cli/about-github-cli （2026-11-08 に確認）
- GitHub CLI manual「gh run view」https://cli.github.com/manual/gh_run_view （2026-11-08 に確認）
- GitHub CLI manual「gh pr edit」https://cli.github.com/manual/gh_pr_edit （2026-11-08 に確認）
- GitHub CLI manual「gh pr create」https://cli.github.com/manual/gh_pr_create （2026-11-08 に確認）
- GitHub CLI manual「gh pr checks」https://cli.github.com/manual/gh_pr_checks （2026-11-08 に確認）
- GitHub CLI manual「gh api」https://cli.github.com/manual/gh_api （2026-11-08 に確認）
- GitHub CLI manual「gh auth token」https://cli.github.com/manual/gh_auth_token （2026-11-08 に確認）
- GitHub Docs「REST API endpoints for workflow jobs」https://docs.github.com/en/rest/actions/workflow-jobs （2026-11-08 に確認）
- GitHub Docs「Rate limits for the REST API」https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api （2026-11-08 に確認）
- GitHub Docs「REST API endpoints for rate limits」https://docs.github.com/en/rest/rate-limit/rate-limit （2026-11-08 に確認）
- GitHub Docs「Rate limits and query limits for the GraphQL API」https://docs.github.com/en/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api （2026-11-08 に確認）
- 社の実測 2026-09-18・2026-09-19・2026-09-20・2026-09-21・2026-09-22・2026-09-23・2026-09-24・2026-09-25・2026-10-13・2026-10-15・2026-10-21（AI の席に gh で GitHub の操作を撃たせた記録）
ブルーランプ 記事の編集部／更新日 2026-11-08