# Analyze GitHub Actions Build
Analyzes a GitHub Actions build to identify failures and their root causes. By default, examines the latest build on the main branch, but you can specify a different run.
## Usage
```
/analyze-build [options]
```
### Options
- `--run-id <id>`: Analyze a specific workflow run by ID
- `--branch <name>`: Analyze the latest run from a specific branch (default: main)
- `--workflow <name>`: Specify which workflow to analyze (default: checks all)
- `--pr <number>`: Analyze the latest run for a specific PR
## Process
1. **Identify Target Build**
- Default: Latest workflow run on main branch
- Or use provided run ID, branch, PR, or workflow name
2. **Gather Build Information**
- Workflow run status and conclusion
- Failed jobs and steps
- Error logs and annotations
- Timing information
- Related commits and PRs
3. **Analyze Failures**
- Parse error messages and stack traces
- Identify failure patterns
- Categorize error types
- Determine root causes
- Check for flaky test indicators
4. **Generate Report**
- Executive summary
- Detailed failure analysis
- Root cause identification
- Suggested fixes
- Historical context (if available)
## Analysis Categories
### 1. Test Failures
- Unit test failures
- Integration test failures
- E2E test failures
- Flaky tests
- Timeout issues
### 2. Build Errors
- Compilation errors
- TypeScript errors
- Dependency resolution issues
- Missing dependencies
- Version conflicts
### 3. Linting/Formatting
- ESLint violations
- Prettier formatting issues
- Commit message format
- Markdown linting
- YAML validation
### 4. Infrastructure Issues
- Runner problems
- Network failures
- API rate limits
- Token/permission issues
- Resource exhaustion
### 5. Deployment Failures
- Docker build issues
- Registry push failures
- Security scan violations
- Release creation problems
## Implementation Steps
```bash
# 1. Get the target workflow run
echo "🔍 Identifying target build..."
# Default: latest run on main
if [ -z "$RUN_ID" ]; then
if [ -n "$PR_NUMBER" ]; then
# Get latest run for PR
RUN_ID=$(gh pr checks $PR_NUMBER --json statusCheckRollup --jq '.statusCheckRollup[0].workflowRun.databaseId')
elif [ -n "$WORKFLOW_NAME" ]; then
# Get latest run for specific workflow
RUN_ID=$(gh run list --workflow="$WORKFLOW_NAME" --branch="${BRANCH:-main}" --limit=1 --json databaseId --jq '.[0].databaseId')
else
# Get latest run on branch
RUN_ID=$(gh run list --branch="${BRANCH:-main}" --limit=1 --json databaseId --jq '.[0].databaseId')
fi
fi
# 2. Fetch run details
echo "📊 Fetching run details for #$RUN_ID..."
gh run view $RUN_ID --json status,conclusion,name,workflowName,event,headBranch,headSha
# 3. Get failed jobs
echo "❌ Identifying failed jobs..."
gh run view $RUN_ID --json jobs --jq '.jobs[] | select(.conclusion == "failure")'
# 4. Fetch logs for failed jobs
echo "📝 Analyzing failure logs..."
gh run view $RUN_ID --log-failed
# 5. Get annotations (errors/warnings)
echo "📌 Checking annotations..."
gh api /repos/{owner}/{repo}/check-runs --jq '.check_runs[].output.annotations[]'
```
## Report Template
```markdown
# Build Analysis Report
**Run ID**: #[RUN_ID]
**Workflow**: [WORKFLOW_NAME]
**Branch**: [BRANCH]
**Status**: [STATUS]
**Duration**: [DURATION]
**Triggered by**: [TRIGGER_EVENT]
## Executive Summary
[High-level summary of the build status and main issues]
## Failure Analysis
### Failed Jobs
1. **[Job Name]** (Duration: [TIME])
- Step: [Failed Step]
- Exit Code: [CODE]
- Category: [Test/Build/Lint/Infrastructure/Deployment]
### Root Cause Analysis
#### Primary Cause
[Identified primary root cause with evidence]
#### Contributing Factors
- [Factor 1]
- [Factor 2]
### Error Details
```
[Relevant error output/stack trace]
````
## Pattern Recognition
### Similar Historical Failures
- [Previous occurrence 1]
- [Previous occurrence 2]
### Flaky Test Indicators
- [Test name if applicable]
- Failure rate: [X/Y runs]
## Recommended Actions
### Immediate Fixes
1. [Specific action to fix the issue]
2. [Additional required changes]
### Long-term Improvements
- [Suggested process improvement]
- [Infrastructure enhancement]
## Additional Context
### Related PRs/Issues
- PR #[NUMBER]: [Title]
- Issue #[NUMBER]: [Title]
### Recent Changes
- Commit [SHA]: [Message]
- Files modified: [List of relevant files]
## Commands to Reproduce/Fix
```bash
# To reproduce locally
[commands]
# To fix
[commands]
# To re-run the workflow
gh run rerun $RUN_ID
````
````
## Common Root Causes and Solutions
### Test Failures
**Pattern: `Cannot find module`**
**Root Cause**: Missing dependency or import path issue
**Solution**:
```bash
pnpm install
# or check import paths in affected files
````
**Pattern:** `Timeout of Xms exceeded`
**Root Cause**: Test timeout, possible performance issue
**Solution**:
- Increase timeout in test configuration
- Investigate performance regression
- Check for missing async/await
### Build Errors
**Pattern:** `Type error TS[NUMBER]`
**Root Cause**: TypeScript compilation error
**Solution**:
```bash
pnpm typecheck
# Fix type errors locally before pushing
```
**Pattern:** `ELIFECYCLE`
**Root Cause**: Script execution failure
**Solution**:
- Check script in package.json
- Verify all dependencies installed
- Check Node version compatibility
### Linting Issues
**Pattern:** `Unexpected var, use let or const`
**Root Cause**: ESLint rule violation
**Solution**:
```bash
pnpm lint:fix
```
**Pattern:** `Trailing spaces`
**Root Cause**: Formatting issue
**Solution**:
```bash
pnpm format:fix
```
### Infrastructure Issues
**Pattern:** `Rate limit exceeded`
**Root Cause**: GitHub API rate limit
**Solution**:
- Add delays between API calls
- Use authentication token
- Implement caching
**Pattern:** `Permission denied`
**Root Cause**: Token permissions insufficient
**Solution**:
- Check workflow permissions
- Update token scopes
- Verify repository settings
### Security/Vulnerability Issues
**Pattern:** `CRITICAL vulnerability found`
**Root Cause**: Dependency vulnerability
**Solution**:
```bash
# Update vulnerable dependency
pnpm update [package]
# or add to .trivyignore if false positive
```
## Example Usage
### Default (latest on main)
```
/analyze-build
```
### Specific run ID
```
/analyze-build --run-id 12345678
```
### Latest on a branch
```
/analyze-build --branch feature/new-feature
```
### For a specific PR
```
/analyze-build --pr 123
```
### Specific workflow
```
/analyze-build --workflow "CI"
```
## Output Example
```
🔍 Analyzing build #12345678...
Build Analysis Report
===================
Run ID: #12345678
Workflow: CI
Branch: main
Status: failure ❌
Duration: 5m 23s
Executive Summary:
The build failed due to TypeScript compilation errors introduced in commit abc123.
Two test files have type mismatches after the recent API client refactoring.
Root Cause:
Missing type exports from src/client/base-client.ts causing import failures in test files.
Immediate Fix:
1. Add missing exports to src/client/base-client.ts:
export type { ClientOptions, ClientResponse }
2. Run locally to verify:
pnpm typecheck
Failed Jobs:
- typecheck (failed after 45s)
Error: TS2305: Module '"./base-client"' has no exported member 'ClientOptions'
Recommended Actions:
✅ Add missing type exports
✅ Run pnpm typecheck locally before pushing
📝 Consider adding pre-push hook to catch type errors
Re-run command:
gh run rerun 12345678
```
## Notes
- Requires `gh` CLI to be authenticated
- Works best with detailed CI logs and annotations
- Can analyze both passed and failed builds
- Provides actionable recommendations based on failure patterns
- Learns from historical patterns in the repository
