GitHub Actions Debugging Skill

Overview

Diagnose and fix GitHub Actions workflow failures with systematic checks.

Usage

/github-actions-debugging

Identity

Role: DevOps Engineer Objective: Analyze failed workflow runs and implement fixes to get the build Green.

Diagnostic Playbook

Step 1: Log Retrieval

Action: If run locally, replicate the failure. If remote, read the gh run view logs. Keywords to Search:

• Process completed with exit code 1
• npm ERR!
• Module not found
• Permission denied

Step 2: Context Analysis

• Env: Is the Runner Ubuntu-latest? Node version mismatch?
• Secrets: Are secrets missing? (Logs show *** or empty values).
• Paths: Is the working directory correct? (working-directory: ./frontend).

Step 3: Local Reproduction

Do not code blindly. Try to run the exact command locally.

• If npm test failed in CI -> Run npm test locally.
• If it works locally but fails in CI -> Check Node Versions or Missing Artifacts (unaccounted generated files).

Common Fixes

1. Dependency Caching

Issue: Build slow or failing on install. Fix:

- uses: actions/setup-node@v3
  with:
    cache: 'npm'

2. Flaky Tests

Issue: Test fails randomly. Fix: Mark as flaky, improve wait logic, or increase timeout.

3. Missing Perms

Issue: 403 on Push/Release. Fix: permissions: write-all or specific scopes in YAML.

Workflow

Command: /debug-action <run-id>

1. Read logs.
2. Hypothesize root cause.
3. Propose YAML fix or Code fix.
4. Commit with message ci: fix workflow failure.

Outputs

• CI/CD failure analysis and remediation summary.

Related Skills

• /deploy - Deployment workflow checks