github-actions-reviewer

GitHub Actions Reviewer

Overview

Structured review of GitHub Actions workflows for consistency, security, and operational best practices.

Core principle: Workflows in the same repo form a system. Review them as a group, not individually — inconsistencies between workflows cause the hardest-to-debug CI failures.

When to Use

• Reviewing CI/CD workflows in any repository
• Auditing workflow permissions and security posture
• Checking for version drift across workflows
• After adding a new workflow to verify consistency with existing ones
• Periodic hygiene check on GitHub Actions setup
• Re-grading after improvements (creates fresh analysis and plan)

When NOT to Use

• Debugging a single workflow run failure (use GitHub's run logs instead)
• Writing new workflows from scratch (this skill reviews existing ones)
• Non-GitHub CI systems (Jenkins, GitLab CI, CircleCI)
• Reviewing application code that happens to be triggered by workflows

Workflow

Read All Workflows + Config -> Evaluate Against Checklist -> Write analysis.md -> Write plan.md -> Ask User to Confirm -> (proceed: Execute / stop: Done / edit: revise plan.md)

Critical Rules

1. ALWAYS write analysis.md and plan.md — Even on re-reviews or when no issues found. Never skip file output.
2. ALWAYS ask user before executing — Never auto-proceed to implementation.
3. Show the user what was written — Summarize key findings after writing files.

Steps

1. Read All Workflows and Config

Read every file in .github/workflows/ plus related config: release tooling configs (release-please-config.json, .releaserc.json, etc.), versions.tf, .tflint.hcl, package.json.

2. Evaluate Against Checklist

Run through the 8-point checklist covering version consistency, plugin/config alignment, permissions, concurrency control, path filters, reusable patterns, action pinning, and secrets handling. See checklist.md for detailed criteria, examples, and red flags.

3. Write analysis.md

Write findings, checklist results, and a letter grade (A-F) to claude/github-actions-review/analysis.md in the target repo. See templates.md for the full template.

4. Write plan.md

Write actionable implementation steps (or confirm no changes needed) to claude/github-actions-review/plan.md. See templates.md for the full template.

5. Ask User to Confirm

Present: "I've written the analysis (Grade: X) and plan (Y steps). Would you like me to proceed, stop here, or wait while you edit plan.md?"

6. Execute Step by Step

For each plan step: announce it, execute, show what changed, update verification checkboxes in plan.md, and confirm before moving to the next step. Stop and ask for input if anything fails.

Common Mistakes

Mistake	Why It Fails	Do Instead
Reviewing workflows individually	Misses cross-workflow inconsistencies (version drift, permission gaps)	Always read all workflows before evaluating any
Skipping file output on re-review	User loses the updated analysis and grade	Always write fresh analysis.md and plan.md
Auto-executing the plan	User hasn't reviewed or approved changes	Always ask for confirmation first
Ignoring release tooling config	Plugin mismatches between preview and release workflows go undetected	Read .releaserc.json, release-please-config.json, etc.
Checking only permissions at workflow level	Job-level permissions override workflow-level	Check both levels

Supporting Files

• checklist.md — Full 8-point review checklist with tables, YAML examples, and red flags
• templates.md — Output templates for analysis.md and plan.md