---
name: analyze-ci-failure-logs
description: Parse and analyze CI failure logs from GitHub Actions to identify root causes across Go, TypeScript/Vue.js, and PHP stacks
category: cicd
mcp_fallback: none
user-invocable: false
---

# CI/CD: Analyze CI Failure Logs

## When to Use

- When a GitHub Actions workflow run fails and the cause is unclear
- To quickly triage CI failures without manually reading raw logs
- When multiple jobs fail and you need to identify the root cause
- To detect patterns in recurring CI failures
- When a teammate reports a failed pipeline and asks for help

## Quick Reference

```bash
# List recent failed runs
gh run list --status failure --limit 5

# View failed run logs
gh run view <run-id> --log-failed

# Download full logs for offline analysis
gh run download <run-id> --dir ci-logs/
```

## Workflow

1. **Identify the failed run**:
   - `gh run list --status failure --limit 5` -- list recent failures
   - `gh run view <run-id>` -- get summary of a specific run
   - Note the workflow name, branch, and triggering event

2. **Download and examine failed logs**:
   - `gh run view <run-id> --log-failed` -- show only failed step output
   - For full logs: `gh run download <run-id> --dir ci-logs/`

3. **Pattern-match failure type by stack**:
   - **Go failures**:
     - Compilation: `cannot find package`, `undefined:`, `imported and not used`
     - Test: `--- FAIL:`, `panic:`, `FAIL\t<package>`
     - Lint: `golangci-lint` output lines with file:line:col format
   - **TypeScript/Vue failures**:
     - Type errors: `TS2xxx:`, `error TS`, `Type '...' is not assignable`
     - Build: `Module not found`, `Cannot find module`, `SyntaxError`
     - Test: `FAIL src/`, `Expected:`, `Received:`, vitest failure output
   - **PHP failures**:
     - Fatal: `PHP Fatal error:`, `Class '...' not found`
     - Test: `FAILURES!`, `Failed asserting`, `PHPUnit` output
     - PHPStan: `Line`, `Error`, phpstan table output

4. **Identify root cause**:
   - Check if the failure is in source code, dependencies, or CI config
   - Look for environment issues: missing secrets, wrong runtime versions
   - Check if the failure reproduces locally

5. **Summarize findings**:
   - Failed job and step name
   - Error message and file location
   - Root cause category (code, config, infra, flaky)
   - Suggested remediation

## Common CI Environment Issues

- **Missing environment variables**: secrets not configured for the repository
- **Version mismatch**: Go/Node/PHP version in CI differs from local
- **Dependency cache stale**: cached modules out of date; clear cache and rebuild
- **Flaky tests**: tests that pass locally but fail intermittently in CI
- **Timeout**: job exceeds the configured time limit

## Error Handling

| Error | Cause | Fix |
|---|---|---|
| `gh: command not found` | GitHub CLI not installed | Install from https://cli.github.com/ |
| `run not found` | Invalid run ID or wrong repository | Verify run ID with `gh run list` |
| `HTTP 403` from `gh` | Insufficient permissions | Re-authenticate: `gh auth login` |
| Logs truncated | GitHub Actions log size limit | Download full logs with `gh run download` |
| Cannot reproduce locally | Environment difference | Match CI versions: check workflow YAML for runtime versions |
| Multiple failures in one run | Cascading failures | Fix the earliest failure first; later ones may resolve |

## References

- GitHub CLI run commands: https://cli.github.com/manual/gh_run
- GitHub Actions troubleshooting: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows
- GitHub Actions log retention: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs