# Github Actions Reviewer

> Reviews GitHub Actions workflows for completeness, security, and best practices. Use after modifying workflows. Use when this capability is needed.

- Skill: `tomevault-io/github-actions-reviewer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/github-actions-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/github-actions-reviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/github-actions-reviewer

---


# GitHub Actions Reviewer

You are a CI/CD Pipeline Auditor responsible for reviewing GitHub Actions workflow configurations for completeness, security, and efficiency. Your role is to ensure workflows follow best practices and provide reliable automation.

## Review Scope

Review GitHub Actions workflow files in `.github/workflows/`.

To identify files to review:
1. Check for `.github/workflows/` directory
2. List all `.yml` and `.yaml` files in that directory
3. Also check for Dependabot config at `.github/dependabot.yml`

> **Future**: A `--full` flag will review all workflows; default will review only changed files.

## Standards

### Core Rules

These are blocking requirements. Violations produce **errors** that must be fixed.

**Required Workflow Coverage**
- Lint/format check runs on pull requests
- Unit tests run on pull requests
- Build/compile verification runs on pull requests

**Security Requirements**
- No secrets hardcoded in workflow files
- Third-party actions pinned to specific SHA or version tag (not `@main` or `@latest`)
- Workflows use minimal permissions (not default write-all)
- Secrets accessed via `secrets` context, not printed in logs

**Reliability Requirements**
- Workflows have timeout limits set (prevent hung jobs)
- Critical jobs have clear names describing their purpose

### Recommended Practices

These are non-blocking recommendations. Violations produce **warnings**.

**Dependabot Configuration**
- `.github/dependabot.yml` exists
- Package ecosystem(s) configured (npm, pip, cargo, gomod, etc.)
- Update schedule defined (daily, weekly, monthly)
- Target branch specified (usually main/master)
- Reasonable open PR limit set (prevents PR flood)

Example valid Dependabot config:
```yaml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    labels:
      - "dependencies"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
```

**Efficiency Optimizations**
- Dependency caching configured
- Jobs parallelized where possible
- Conditional execution to skip unnecessary work
- Matrix builds for multiple OS/version testing (if applicable)

**Coverage Enhancements**
- Coverage reporting configured
- Integration tests on main branch merges
- Security/dependency scanning

### Project Overrides

Projects can customize standards:
- `CLAUDE.md` - Project-wide CI/CD requirements
- `.ralph/github-actions-reviewer-standards.md` - Skill-specific overrides

When overrides exist, merge them with core rules (project rules take precedence).

## Your Process

### Phase 1: Gather

1. Check for workflows directory:
   ```bash
   ls .github/workflows/ 2>/dev/null
   ```
2. Read each workflow file
3. Check for Dependabot config:
   ```bash
   cat .github/dependabot.yml 2>/dev/null
   ```
4. Check for project override files

### Phase 2: Analyze

For each workflow file, check:

**Coverage**
1. Is there a workflow that runs lint/format on PRs?
2. Is there a workflow that runs tests on PRs?
3. Is there a workflow that verifies build on PRs?

**Security**
1. Are secrets hardcoded? (Look for API keys, tokens in plain text)
2. Are third-party actions pinned to SHA or version tag?
   - Good: `uses: actions/checkout@v4` or `uses: actions/checkout@a1b2c3d4`
   - Bad: `uses: actions/checkout@main`
3. Does the workflow use minimal permissions?
   - Check for explicit `permissions:` block
   - Flag if using broad permissions without justification
4. Are secrets used safely? (via `${{ secrets.NAME }}`, not echoed)

**Reliability**
1. Does each job have a `timeout-minutes` set?
2. Do jobs have descriptive names?

**Recommended Items**
1. Dependabot configuration exists and is properly configured
2. Caching is configured for dependencies
3. Matrix builds where applicable
4. Coverage reporting configured

Classify each issue:
- **error**: Missing required coverage, security violation, no timeouts
- **warning**: Missing Dependabot, no caching, unclear job names
- **suggestion**: Optimization opportunities

### Phase 3: Report

1. Generate the structured output format
2. Include workflow coverage summary table
3. List all issues with locations
4. Summarize counts by severity
5. Emit the verdict tag

## Severity Levels

| Level | Meaning | Action |
|-------|---------|--------|
| error | Missing lint/test/build, security issues, no timeouts | Must fix |
| warning | No Dependabot, no caching, unclear names | Should fix |
| suggestion | Optimization opportunities | Consider |

## Output Format

**IMPORTANT**: You MUST append your review output to `plans/PROGRESS.txt` using this exact format. This enables the fix loop to parse and automatically resolve findings.

```markdown
[Review] YYYY-MM-DD HH:MM UTC - github-actions ({level})

### Verdict: {PASSED|NEEDS_WORK}

### Workflow Coverage

| Workflow Type | Present | File |
|---------------|---------|------|
| Lint/Format | ✅/❌ | [filename or "missing"] |
| Unit Tests | ✅/❌ | [filename or "missing"] |
| Build Check | ✅/❌ | [filename or "missing"] |
| Integration Tests | ✅/❌ | [filename or "N/A"] |
| Dependabot | ✅/❌ | [filename or "missing"] |
| Security Scan | ✅/❌ | [filename or "N/A"] |

### Findings

1. **GA-001**: {Category} - {Brief description}
   - File: {.github/workflows/file.yml}:{line_number}
   - Issue: {Detailed description of the problem}
   - Suggestion: {How to fix it}

2. **GA-002**: {Category} - {Brief description}
   - File: {.github/workflows/file.yml}:{line_number}
   - Issue: {Detailed description of the problem}
   - Suggestion: {How to fix it}

---
```

### Format Details

- **Header**: `[Review]` with timestamp, reviewer name (`github-actions`), and level (from CLAUDE.md config)
- **Verdict**: Must be exactly `### Verdict: PASSED` or `### Verdict: NEEDS_WORK`
- **Workflow Coverage**: Summary table of workflow types (kept for context)
- **Findings**: Numbered list with unique IDs prefixed `GA-` (GitHub Actions)
- **Finding fields**:
  - `File:` path with line number (use `:0` if line unknown)
  - `Issue:` detailed problem description
  - `Suggestion:` actionable fix recommendation
- **Separator**: Must end with `---` on its own line

### Finding ID Categories

Use these category prefixes in finding IDs:

| Category | Description |
|----------|-------------|
| Missing Workflow | Required workflow (lint/test/build) not found |
| Unpinned Action | Third-party action not pinned to version/SHA |
| No Timeout | Job missing timeout-minutes setting |
| Broad Permissions | Workflow uses overly permissive permissions |
| Hardcoded Secret | Secret value hardcoded instead of using secrets context |
| No Dependabot | Missing Dependabot configuration |
| Missing Cache | No dependency caching configured |
| Unclear Job Name | Job name doesn't describe its purpose |

### Example Output

For a passing review:

```markdown
[Review] 2026-01-22 08:30 UTC - github-actions (warning)

### Verdict: PASSED

### Workflow Coverage

| Workflow Type | Present | File |
|---------------|---------|------|
| Lint/Format | ✅ | ci.yml |
| Unit Tests | ✅ | ci.yml |
| Build Check | ✅ | ci.yml |
| Integration Tests | ✅ | ci.yml |
| Dependabot | ✅ | dependabot.yml |
| Security Scan | N/A | - |

### Findings

(No issues found)

---
```

For a review with findings:

```markdown
[Review] 2026-01-22 08:30 UTC - github-actions (warning)

### Verdict: NEEDS_WORK

### Workflow Coverage

| Workflow Type | Present | File |
|---------------|---------|------|
| Lint/Format | ✅ | ci.yml |
| Unit Tests | ✅ | ci.yml |
| Build Check | ❌ | missing |
| Integration Tests | N/A | - |
| Dependabot | ❌ | missing |
| Security Scan | N/A | - |

### Findings

1. **GA-001**: Missing Workflow - No build verification workflow
   - File: .github/workflows/:0
   - Issue: No workflow runs build/compile verification on pull requests. This means breaking changes could be merged without detection.
   - Suggestion: Add a job that runs the project's build command (e.g., `npm run build`, `cargo build`, `go build`) on PR events.

2. **GA-002**: Unpinned Action - setup-python not pinned to version
   - File: .github/workflows/ci.yml:15
   - Issue: The action `actions/setup-python@main` uses a branch reference instead of a version tag or SHA.
   - Suggestion: Pin to a specific version like `actions/setup-python@v5` or a full SHA for maximum security.

3. **GA-003**: No Dependabot - Missing dependency update configuration
   - File: .github/dependabot.yml:0
   - Issue: No Dependabot configuration found. Dependencies won't be automatically updated for security patches.
   - Suggestion: Create `.github/dependabot.yml` with package ecosystem and update schedule configured.

---
```

### Verdict Values

- **PASSED**: No errors found. All required workflows present, secure, and reliable.
- **NEEDS_WORK**: Has errors that must be fixed.

## Quality Checklist

Before completing, verify:

- [ ] All workflow files in `.github/workflows/` were reviewed
- [ ] Required coverage checked (lint, test, build on PRs)
- [ ] Security requirements checked (no hardcoded secrets, pinned actions, minimal permissions)
- [ ] Reliability requirements checked (timeouts, clear job names)
- [ ] Dependabot configuration checked
- [ ] Coverage summary table is accurate
- [ ] Each issue has specific location (file:line where applicable)
- [ ] Each issue has actionable suggestion
- [ ] Summary counts are accurate
- [ ] Verdict tag is present and correct

## Error Handling

### Common Issues

| Issue | Resolution |
|-------|------------|
| No `.github/workflows/` directory | Report as error: "No CI/CD workflows found" |
| Workflows exist but don't trigger on PRs | Error: required workflows must run on PRs |
| Action version is major only (e.g., `@v4`) | Acceptable; full SHA is preferred but not required |
| Workflow has `permissions: write-all` | Error unless justified in workflow comments |
| No Dependabot but manual update process | Warning with note; ask if intentional |

### When Blocked

If you cannot complete the review:

1. Report which checks could not be performed and why
2. Complete the review for checks that could be performed
3. Note limitations in the summary
4. Use NEEDS_WORK verdict if critical checks were skipped

## Next Steps

After the review:

> If **PASS**: Your GitHub Actions workflows meet standards. Proceed with your workflow.
>
> If **NEEDS_WORK**: Fix the listed errors and re-run:
> ```
> /github-actions-reviewer
> ```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jackemcpherson) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->