fix-ci-failures

Investigating and Fixing CI Failures

This skill guides you through diagnosing and fixing CI failures on a PR using the gh CLI. The user has the PR branch checked out locally.

Workflow Overview

1. Identify the current branch and its PR
2. Check CI status and find failed checks
3. Download logs for failed jobs
4. Extract and understand the failure
5. Fix the issue and push

Step 1: Identify the Branch and PR

# Get the current branch name
git branch --show-current
 
# Find the PR for this branch
gh pr view --json number,title,url,statusCheckRollup

If no PR is found, the user may need to specify the PR number.

Step 2: Check CI Status

# List all checks and their status (pass/fail/pending)

The link field contains the URL to the GitHub Actions job. Extract the run ID from the URL — it's the number after /runs/:

If checks are still IN_PROGRESS, wait for them to complete before downloading logs:

Step 3: Get Failed Job Details

Step 4: Download Failure Logs

There are two approaches depending on the type of failure.

Option A: View Failed Step Logs Directly

Best for build/compile/lint failures where the error is in the step output:

Important: --log-failed requires the entire run to complete, not just the failed job. If other jobs are still running, this command will block or error. Use Option C below to get logs for a completed job while the run is still in progress.

The output can be large. Pipe through tail or grep to focus:

Option B: Download Artifacts

Best for integration test failures where detailed logs (terminal logs, ext host logs, crash dumps) are uploaded as artifacts:

Tip: Use the test runner name from the failed check (e.g., "Linux / Electron" → electron, "Linux / Remote" → remote) and platform map ("Windows" → windows-x64, "Linux" → linux-x64, "macOS" → macos-arm64) to construct the artifact name.

Warning: Log artifacts may be empty if the test runner crashed before producing output (e.g., Electron download failure). In that case, fall back to Option C.

Option C: Download Per-Job Logs via API (works while run is in progress)

When the run is still in progress but the failed job has completed, use the GitHub API to download that job's step logs directly:

Then search the saved file. Start with ##[error] — this is the GitHub Actions error annotation that marks the exact line where the step failed:

If ##[error] doesn't reveal enough, use broader patterns:

Why save to a file? The API response for a full job log can be 30k+ lines. Tool output gets truncated, so always redirect to a file first, then search.

VS Code Log Artifacts Structure

Downloaded log artifacts typically contain:

Key files to examine first:

• Test assertion failures: Check exthost.log for the extension host output and stack traces
• Terminal/sandbox issues: Check terminal.log for rewriter pipeline, shell integration, and strategy logs
• Crash/hang: Check main.log and look for crash dumps artifacts

Step 5: Extract the Failure

For Test Failures

Look for the test runner output in the failed step log:

Common patterns in VS Code CI:

• AssertionError [ERR_ASSERTION]: Test assertion failed — check expected vs actual values
• Extension host test runner exit code: 1: Integration test suite had failures
• Command produced no output: Shell integration may not have captured command output (see terminal.log)
• Error: Timeout: Test timed out — could be a hang or slow CI machine

For Build Failures

Step 6: Determine if Failures are Related to the PR

Before fixing, determine if the failure is caused by the PR changes or is a pre-existing/infrastructure issue:

1. Check if the failing test is in code you changed — if the test is in a completely unrelated area, it may be a flake
2. Check the test name — does it relate to the feature area you modified?
3. Look at the failure output — does it reference code paths your PR touches?
4. Check if the same tests fail on main — if identical failures exist on recent main commits, it's a pre-existing issue
5. Look for infrastructure failures — network timeouts, npm registry errors, and machine-level issues are not caused by code changes

Recognizing Infrastructure / Flaky Failures

Not all CI failures are caused by code changes. Common infrastructure failures:

Network / Registry issues:

• npm ERR! network, ETIMEDOUT, ECONNRESET, EAI_AGAIN — npm registry unreachable
• error: RPC failed; curl 56, fetch-pack: unexpected disconnect — git network failure
• Error: unable to get local issuer certificate — TLS/certificate issues
• rate limit exceeded — GitHub API rate limiting
• HTTPError: Request failed with status code 502 on electron/electron/releases — Electron CDN download failure (common in the node.js integration tests step, which downloads Electron at runtime)

Machine / Environment issues:

• No space left on device — CI disk full
• ENOMEM, JavaScript heap out of memory — CI machine ran out of memory
• The runner has received a shutdown signal — CI preemption / timeout
• Error: The operation was canceled — GitHub Actions cancelled the job
• Xvfb failed to start — display server for headless Linux tests failed

Test flakes (not infrastructure, but not your fault either):

• Timeouts on tests that normally pass — slow CI machine
• Race conditions in async tests
• Shell integration not reporting exit codes (see terminal.log for exitCode: undefined)

What to do with infrastructure failures:

1. Don't change code — the failure isn't caused by your PR
2. Re-run the failed jobs via the GitHub UI or:

   gh run rerun <RUN_ID> --failed
3. If failures persist across re-runs, check if main is also broken:

   gh run list --branch main --limit 10 --json databaseId,conclusion,displayTitle
4. If main is broken too, wait for it to be fixed — your PR is not the cause

Step 7: Fix and Iterate

1. Make the fix locally
2. Verify compilation: check the VS Code - Build task or run npm run typecheck-client
3. Run relevant unit tests locally: ./scripts/test.sh --grep "<pattern>"
4. Commit and push:

   git add -A
   git commit -m "fix: <description>"
   git push
5. Watch CI again:

Quick Reference