GitHub CLI: Reading and Fixing Pipeline Status#
The gh CLI is the supported way to read CI status for these repositories from
a Windows dev box. It replaces opening the Actions tab in a browser, and — more
importantly for an agent — it makes “is the pipeline green?” a question that can
be answered from a shell, on a schedule, without a human looking at anything.
Install and PATH#
Installed via winget:
winget install --id GitHub.cli
A shell that was already open when gh was installed will not find it.
winget adds the install directory to the user PATH, and existing processes keep
the environment they started with. This bites agents specifically, because a
long-running session’s shell predates the install and reports
gh: command not found for a tool that is present and working.
Two ways out, in order of preference:
Start a new shell.
Call it by full path:
C:\Program Files\GitHub CLI\gh.exe.
The Git Bash tool has its own PATH and may not see winget’s user PATH at all
even in a fresh shell. Prefer PowerShell for gh.
Verify:
gh --version
gh auth status
gh auth status must show the account and, critically, the token scopes.
Reading Actions logs needs repo. A token with only read:org and gist will
list runs and then fail on --log-failed with a permissions error that does not
mention scopes.
Reading pipeline status#
Run from inside the repository — gh infers the repo from the git remote.
# What ran recently, and what did it conclude?
gh run list --limit 10
# Only the failures
gh run list --limit 20 --status failure
# One workflow
gh run list --workflow "Linux build + test + coverage on Ubuntu 24.04 x86"
# Watch an in-progress run to completion
gh run watch <run-id>
# Re-run just the failed jobs
gh run rerun <run-id> --failed
Finding out WHY a run failed#
This is the part that is easy to get wrong, and the ordering below is the whole point of this document.
Do not start with gh run view <id> --log-failed. It emits the entire log
of every failed job — for these builds that is tens of thousands of lines,
including the full llvm-ar command line for the antlr4 runtime, which alone is
a single ~15 KB line. Grepping it for error returns mostly the runner’s own
apt-get cleanup echoes. It will fill a context window and tell you nothing.
Start by asking which step failed:
gh run view <run-id> --json jobs --jq '.jobs[] | .name + " => " + .conclusion, (.steps[] | select(.conclusion=="failure") | " FAILED STEP: " + .name)'
That returns one or two lines — e.g. FAILED STEP: Run fuzzer tests — which is
usually enough to know where to look, and always enough to grep the full log
with a pattern that matches the actual failure rather than the word “error”.
Only then go to the log, filtered:
$log = gh run view <run-id> --log-failed | Out-String
$log -split "`n" | Select-String "SUMMARY:|FAILED|Fatal" | Select-Object -Last 20
SUMMARY: is the useful anchor for sanitizer failures (ASan/UBSan print it as
the last line of a report). [ FAILED ] is the GoogleTest anchor.
Periodic checking#
The intended cadence for an agent working this repository: check CI after
every push, and again before starting unrelated work. The reason is specific
to this project — the Linux lane runs configurations the Windows dev box does
not. ASan/UBSan fuzzing runs there and not here, so a class of bug exists that
is only observable through CI. A green local commitTestSuite.exe is not
evidence that the pipeline is green.
# Did my last push survive?
gh run list --limit 5 --json conclusion,name,headBranch,displayTitle --jq '.[] | .conclusion + " " + .name'
A run reporting skipped is not a pass. Several workflows here are gated (the
Windows container build is gated on [build-win] appearing in the commit
message), and a gated-off workflow reports skipped, which is easy to read as
success at a glance.
Scope#
Reading status, logs, and re-running failed jobs is routine. Cancelling other people’s runs, editing workflow files to make a failure go away, or disabling a workflow is not — a failing pipeline is information, and the fix belongs in the code that failed.