GitHub Actions Debugger

Diagnoses failed GitHub Actions CI/CD runs. Analyzes runner logs, step syntax, matrix jobs, dependency caching, and environment secret injection.

1. Purpose

Pinpoint why a GitHub Actions pipeline failed and provide the exact .github/workflows/*.yml patch.

2. When to Use

Use this skill when:

• A GitHub Actions CI run turns red (exit code 1).
• Steps fail due to missing dependencies, invalid secrets, or runner environment differences.
• Optimizing workflow run times with caching.

3. When Not to Use

• Do not use for local CLI command diagnostics; use command-failure-diagnoser.

4. Required Inputs

• workflow_file: Path to .github/workflows/<name>.yml.
• failure_log: Excerpt from the failing GitHub Actions job step.

5. Missing-Input Behavior

1. If log is missing: inspect .github/workflows/ and ask for the failing step name and error output.
2. Never commit plaintext secrets to workflow files; always use ${{ secrets.NAME }}.

6. Procedure

Follow these numbered actions:

1. Action 1: Identify Failing Step
   • Find the exact step in the YAML file where the runner exited non-zero.
2. Action 2: Classify Failure Mechanism
   • Missing Tool / Setup: Needs actions/setup-node or actions/setup-python.
   • Permission Issue: Needs permissions: contents: write or pull-requests: write.
   • Secret Missing: Environment variable empty in runner.
   • Matrix Mismatch: Fails on specific OS/Node version combination.
3. Action 3: Apply Targeted Patch
   • Edit the workflow file cleanly.
4. Action 4: Emit Debug Report
   • Format per Section 8.

7. Decision Rules

• If failure happens on pull requests from forks: check if secrets are inaccessible (fork security boundary).
• Always pin actions to full commit SHA or trusted major tag (actions/checkout@v4).

8. Output Format

Emit the report using this template:

### GitHub Actions Debug Report: [Workflow Name]

- **Failing Step**: `[Step name]`
- **Root Cause**: [e.g. Missing setup-python step before poetry install]
- **File**: `.github/workflows/[file].yml`

#### Fix Applied
```diff
[Diff of workflow file]

Verification Instructions

• Push commit or re-run workflow to verify green checkmark.

## 9. Verification Checklist
- [ ] Workflow YAML is syntactically valid.
- [ ] No plaintext secrets added.
- [ ] Permissions use least privilege.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| `Resource not accessible by integration` | GITHUB_TOKEN lacks write permission | Add `permissions: pull-requests: write`. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- Workflow requires organizational repository secrets only repository admins can set.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
File: .github/workflows/ci.yml
Error: pnpm: command not found in step 'Install dependencies'

Output:

### GitHub Actions Debug Report: ci.yml

- **Failing Step**: `Install dependencies`
- **Root Cause**: `pnpm` is not installed on the GitHub-hosted runner by default.
- **File**: `.github/workflows/ci.yml`

#### Fix Applied
```diff
+     - uses: pnpm/action-setup@v3
+       with:
+         version: 9
       - uses: actions/setup-node@v4
         with:
           node-version: 20
+          cache: 'pnpm'

Verification Instructions

• Re-run CI job; pnpm will be installed before pnpm install executes.

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Fix actions.

Output:

### GitHub Actions Debug Report: Halted - Missing Log

- **Status**: Halted

Please provide the failing workflow file name and error log excerpt.

Example 3: Expected Final Output

Output:

### GitHub Actions Debug Report: test.yml

- **Failing Step**: `Run tests`
- **Root Cause**: Node version matrix missing dependencies on Node 18.