ci-status-checker

Interprets GitHub Actions run status and logs, diagnoses CI failure patterns, and suggests targeted fixes. Handles dependency install failures, test timeouts, build OOM, flaky tests, and workflow misc

SKILL.md

GitHub

CI Status Checker

Diagnoses CI/CD pipeline failures by reading GitHub Actions logs, identifying failure patterns, and producing actionable fix recommendations. This skill does not write workflows from scratch -- it triages what went wrong with existing ones.

Activation Triggers

Activate on: "CI failing", "build broken", "workflow error", "GitHub Actions debug", "flaky CI", "pipeline timeout", "CI red", "actions run failed", "check failed on PR", "why is CI broken"

NOT for: Writing new workflows --> github-actions-pipeline-builder | Caching strategy --> ci-cache-optimizer | Deployment pipelines --> devops-automator | Performance testing --> performance-profiler

Core Capabilities

  • Read GitHub Actions run logs and extract the failing step with surrounding context
  • Classify failures into known categories (dependency, build, test, timeout, OOM, permissions, config)
  • Suggest targeted fixes based on error pattern matching against known CI failure modes
  • Detect workflow YAML syntax and configuration issues before they cause runtime failures
  • Identify flaky tests by analyzing pass/fail patterns across recent runs
  • Check for common misconfigurations: wrong Node version, missing secrets, incorrect paths
  • Diagnose matrix build failures where only specific combinations fail
  • Trace failure cascades (step A fails silently, step B fails loudly because of A)

Diagnostic Process

Step 1: Get Run Status

# Check most recent run status
gh run list --limit 5

# Get details for a specific failed run
gh run view <run-id>

# Get the full log for a failed run
gh run view <run-id> --log-failed

Always start with --log-failed rather than --log to avoid pulling megabytes of passing step output. Only escalate to full logs if the failed step output is insufficient.

Step 2: Identify the Failing Step

Parse the log output to find the first step that failed. CI logs contain noise -- focus on:

  1. The step name that shows a red X
  2. The last 50 lines of that step's output
  3. The exit code (non-zero)
  4. Any ##[error] annotations

Step 3: Classify the Failure

Failure Classification Guide

Category 1: Dependency Installation Failures

Signals:

  • npm ERR! or yarn error in install step
  • ERESOLVE unable to resolve dependency tree
  • 404 Not Found for a package
  • ENOENT for lockfile
  • pip install failures with version conflicts
  • Could not find a version that satisfies the requirement

Common causes and fixes:

Error Pattern Likely Cause Fix
ERESOLVE peer dependency conflict Incompatible package versions npm install --legacy-peer-deps or fix version constraints
404 Not Found for package Package unpublished or registry down Check npm status, pin working version
ENOENT package-lock.json Lockfile not committed Commit lockfile, or use npm install instead of npm ci
engine "node" incompatible Wrong Node version in CI Match node-version in workflow to engines in package.json
ENOMEM during install Runner out of memory Use larger runner or reduce parallelism
ETARGET no matching version Version range resolves to nothing Pin specific version, check if package was yanked

Category 2: Build Failures

Signals:

  • TypeScript errors: TS2304, TS2339, TS2345, etc.
  • Module not found or Cannot find module
  • SyntaxError: Unexpected token
  • Build step exits non-zero

Common causes and fixes:

Error Pattern Likely Cause Fix
TS2307: Cannot find module Missing type declarations Install @types/* package or add to tsconfig.json paths
TS2345: Argument of type Type mismatch introduced in PR Fix the type error in source code
Module not found: 'X' Import path wrong or package missing Check import paths, verify package in dependencies
JavaScript heap out of memory Build exceeds Node memory limit Add NODE_OPTIONS=--max-old-space-size=4096 to env
SIGKILL during build OOM killer terminated process Use larger runner (ubuntu-latest-4-cores) or optimize build

Category 3: Test Failures

Signals:

  • Test runner reports failures with assertion messages
  • FAIL markers in Jest/Vitest output
  • Expected X but received Y
  • Test timeout exceeded

Common causes and fixes:

Error Pattern Likely Cause Fix
Assertion failure with clear diff Real bug introduced in PR Fix the code (not the test, unless test is wrong)
Timeout on async test Missing await or slow operation Add proper await, increase timeout, or mock slow calls
ECONNREFUSED in test Test needs running service Use service containers or mock the dependency
Snapshot mismatch Intentional UI change Update snapshots with --update-snapshot if change is correct
Different results on CI vs local Environment difference Check timezone, locale, file ordering, parallelism

Category 4: Timeout Failures

Signals:

  • The job running on runner ... has exceeded the maximum execution time
  • Step shows no output for extended period then dies
  • ##[error]The operation was canceled

Common causes and fixes:

Error Pattern Likely Cause Fix
Job timeout (6h default) Infinite loop or hung process Set explicit timeout-minutes per job, investigate hang
Step hangs with no output Interactive prompt waiting for input Add -y or --yes flags, pipe yes, set CI=true env
E2E test timeout Browser not starting or page not loading Check playwright install --with-deps, add retry
Docker build timeout Layer cache miss on large image Use docker/build-push-action with cache-from

Category 5: Permission and Secret Failures

Signals:

  • Error: Resource not accessible by integration
  • Error: Input required and not supplied: token
  • fatal: could not read Username
  • 403 Forbidden on API calls

Common causes and fixes:

Error Pattern Likely Cause Fix
Resource not accessible Insufficient GITHUB_TOKEN permissions Add permissions: block to workflow
Input required: token Secret not available in fork PRs Use pull_request_target or conditional step
could not read Username Private repo access without token Use actions/checkout with token: ${{ secrets.PAT }}
403 on deployment Deploy key or token expired Rotate secret in repo settings

Category 6: Workflow Configuration Errors

Signals:

  • Invalid workflow file before any step runs
  • Unexpected value in YAML parsing
  • Steps reference nonexistent actions or wrong versions

Common causes and fixes:

Error Pattern Likely Cause Fix
Invalid workflow file YAML syntax error Validate with actionlint locally
Unexpected value 'X' Wrong key name or indentation Check GitHub Actions schema for correct key names
Unable to resolve action Action not found or wrong version Verify action exists, use @v4 not @master
Context access might be invalid Typo in ${{ }} expression Check variable names against available contexts

Flaky Test Analysis

Flaky tests are tests that pass and fail nondeterministically. They erode trust in CI. Diagnose by pattern:

Detection

# Get last 20 runs for the test job
gh run list --workflow=tests.yml --limit 20 --json status,conclusion,startedAt

# Compare pass/fail ratio
gh run list --workflow=tests.yml --limit 50 --json conclusion | \
  jq 'group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})'

If the same workflow alternates between success and failure without code changes, you have flaky tests.

Common Flaky Patterns

  1. Race condition: Tests share mutable state. Fix: isolate test state, use beforeEach reset.
  2. Timing dependency: Test assumes operation completes in N ms. Fix: use polling/waitFor instead of sleep.
  3. Order dependency: Test passes in isolation but fails when run after another test. Fix: ensure cleanup in afterEach.
  4. Port collision: Multiple test suites bind to same port. Fix: use random ports or --shard.
  5. Timezone/locale: Test passes in US locale but fails in CI (usually UTC). Fix: set TZ=UTC in test env.
  6. File system ordering: readdir returns different order on different OS. Fix: sort results before comparing.

Quarantine Strategy

If a flaky test cannot be fixed immediately:

  1. Move to a flaky/ directory or tag with .skip + a TODO comment with issue link
  2. Create a tracking issue with reproduction details
  3. Set a deadline (2 weeks max) for resolution
  4. Never delete a flaky test -- it caught a real issue at least once

Workflow Validation

Before a workflow runs in CI, validate it locally:

# Install actionlint (the gold standard for workflow linting)
brew install actionlint  # macOS
# or: go install github.com/rhysd/actionlint/cmd/actionlint@latest

# Lint all workflow files
actionlint .github/workflows/*.yml

# Check a specific file with verbose output
actionlint -verbose .github/workflows/ci.yml

Common YAML Pitfalls

  1. Unquoted on: triggers: on: push works, but on: [push, pull_request] needs the brackets
  2. Missing runs-on: Every job needs it
  3. Wrong indentation: Steps under steps: must be at the right level
  4. Expression syntax: ${{ github.event.pull_request.number }} not ${ github.event... }
  5. Matrix include/exclude: include adds combinations, it does not filter -- use exclude to remove

Anti-Patterns

1. Retry Until Green

Symptom: Re-running failed workflow until it passes Why wrong: Masks real issues, wastes compute minutes, teaches team to ignore CI Fix: Investigate every failure. If genuinely flaky, quarantine the test and fix the root cause.

2. Disabling Failing Checks

Symptom: Removing status checks from branch protection because they fail Why wrong: Opens main branch to broken code Fix: Fix the check, or mark it as continue-on-error: true with a tracking issue.

3. Blaming the Runner

Symptom: "CI is slow/broken, works on my machine" Why wrong: CI environment differences are the test -- if it fails there, the code has assumptions Fix: Match CI environment locally. Use act or Docker to reproduce. Add CI=true to local test runs.

4. Giant Log Dumps

Symptom: Pasting entire CI log into an issue or PR comment Why wrong: No one reads 10,000 lines of logs Fix: Extract the relevant 10-20 lines around the failure. Include the step name, error message, and exit code.

5. Ignoring Warnings

Symptom: CI passes but with deprecation warnings, security advisories, or linting warnings Why wrong: Warnings become errors in the next major version. Technical debt compounds. Fix: Treat warnings as errors in CI (--max-warnings 0 for ESLint, --strict for TypeScript).

6. Monolithic Workflow Files

Symptom: Single 500-line workflow file that does lint + test + build + deploy Why wrong: One failure blocks everything, hard to debug, impossible to re-run selectively Fix: Split into separate workflows or use reusable workflows with workflow_call.

Decision Points

When to escalate vs fix locally

  • Fix locally: Dependency version bump, lockfile update, snapshot update, env variable typo
  • Escalate: Infrastructure issue (GitHub Actions outage), permission change needed (admin-only), flaky test requiring architecture change

When a failure is infrastructure vs code

Check https://www.githubstatus.com/ first. If Actions shows degraded:

  • Note the incident in the PR
  • Wait and re-run
  • Do NOT push empty commits to trigger reruns

If infrastructure is healthy, the failure is yours to own.

When matrix failures are partial

If only node-18, ubuntu-latest fails but node-20, ubuntu-latest passes:

  • The fix is probably a Node 18 compatibility issue
  • Check if the project's engines.node matches the matrix
  • Consider dropping the failing version if it is EOL

Quality Checklist

[ ] Identified the exact failing step (not just "CI failed")
[ ] Classified failure into correct category (dependency/build/test/timeout/permission/config)
[ ] Reproduced locally when possible (or explained why not)
[ ] Fix addresses root cause, not symptoms (no blind retries)
[ ] Flaky tests either fixed or quarantined with tracking issue
[ ] Workflow YAML validates with actionlint after changes
[ ] CI minutes impact considered (larger runner = more cost)
[ ] Secrets verified as available for the trigger type (push vs pull_request vs fork)
[ ] Timeout values set explicitly on long-running jobs
[ ] Status check passes on the fix PR before merging

Quick Reference Commands

# List recent workflow runs
gh run list --limit 10

# View a specific run (shows jobs and steps)
gh run view <run-id>

# Get only failed step logs
gh run view <run-id> --log-failed

# Re-run failed jobs only (not the whole workflow)
gh run rerun <run-id> --failed

# Watch a running workflow
gh run watch <run-id>

# List workflow files
ls .github/workflows/

# Validate workflow syntax locally
actionlint .github/workflows/*.yml

# Check GitHub Actions service status
open https://www.githubstatus.com/

# Run workflow manually (if workflow_dispatch enabled)
gh workflow run <workflow-name>

Covers: GitHub Actions diagnosis | Failure classification | Flaky test analysis | Workflow validation | Permission debugging | Timeout investigation

Use with: github-actions-pipeline-builder (create workflows) | ci-cache-optimizer (fix cache issues) | test-automation-expert (fix failing tests) | site-reliability-engineer (production CI/CD)