GitHub Actions zero-step failures are not code review

A red CI check is not always a code failure.

That sounds obvious until an agent sees a failed GitHub Actions run, opens the workflow file, and starts "fixing" YAML before asking whether the job ever started. If there are no steps, no logs, and no setup output, you may not have a broken test. You may have a runner, account, billing, permissions, or platform gate.

GitHub's own docs draw the line clearly enough. A normal Actions job has logs. GitHub adds setup and completion steps around the configured workflow steps. Workflow runs map to check suites and check runs through the Checks API. Check runs carry status, conclusion, output, details URLs, and annotations. That is where an agent should look before it edits code.

Sources: GitHub Actions workflow run logs, GitHub REST API check runs, GitHub Actions events that trigger workflows, GitHub CLI manual for gh run view.

No logs is a fact, not a vibe

When a workflow fails inside the repo, there is usually evidence. A failing install step prints npm output. A broken build prints a stack trace. A bad test prints an assertion. Even setup failure tends to show something in the "Set up job" step.

A zero-step failure is different. The absence of logs is part of the bug report.

The wrong agent move is to patch .github/workflows/build.yml because the check is red. That turns an infrastructure diagnosis into random code churn. The better move is to read the run and the check run directly:

gh run view <run-id> --json status,conclusion,jobs,url,event,headSha

gh api repos/<owner>/<repo>/commits/<sha>/check-runs \
  --jq '.check_runs[] | {name,status,conclusion,details_url,output}'

gh api repos/<owner>/<repo>/check-runs/<check-run-id>/annotations

If the annotations say the job did not start, believe them. If the job list is empty or the details URL points to an account-level problem, the repo did not get a fair trial.

CI should classify the failure before fixing it

I want agents to add one habit to their CI loop: classify before repair.

A useful classification is small:

code_failure: logs exist and a repo command failed
workflow_config_failure: YAML parsed, job started, config caused the failure
platform_failure: job never started or no runner/account resource was available
permission_failure: token, branch, or event context blocked the job
unknown: evidence missing, do not edit yet

That last line matters. Unknown is a real state. It is not a license to invent the most familiar fix.

This is especially important for repos with deploy gates. If the build is locally green, the workflow file has not changed, and GitHub shows a check run with no steps, changing package scripts is noise. The thing to do is attach the local build output, attach the check-run annotation, and call the external gate by its name.

The Checks API is the audit trail

GitHub Actions pages are useful for humans. The Checks API is better for agents.

A workflow run can contain jobs. Jobs produce steps. Check runs summarize the result that branch protection sees. GitHub's docs say Actions use the Checks API for statuses, results, and logs, and that each workflow run creates a check suite with check runs for jobs. That means the agent should report both layers: the workflow run and the check run.

I want reports that look like this:

Run: <url>
Head SHA: <sha>
Workflow status: completed
Workflow conclusion: failure
Jobs: 0, or job has no steps
Check run: Build
Check conclusion: failure
Annotation: <exact message>
Local build: passed / failed, with command
Decision: code fix / platform blocker / needs human

That is less glamorous than "I fixed CI." It is also much harder to fake.

Red does not always mean editable

Agents are very good at doing the next editable thing. That is the danger.

A red check makes the workflow file feel like the nearest handle. Sometimes it is. Plenty of CI failures come from stale Node versions, missing environment variables, wrong paths, or scripts that only worked on one machine.

But if the job never started, the code did not fail. The platform refused to run it. Treating that as a code review problem is how you turn a clean PR into a mess.

The rule I use now is blunt: no steps, no rewrite. Inspect the check run first. Read the annotation. Then decide whether the repo needs a patch or the account needs attention.