Workflow Audit

Workflow Audit

Comprehensive audit of .github/workflows/*.yml files against GitHub Actions best practices, security hardening guidelines, and project conventions.

When to Use

• User asks to audit, review, or check workflows
• Before committing changes to any workflow file
• After a workflow failure that needs root-cause analysis
• Periodic health check (e.g., monthly)

Workflow

1. Discover — Glob .github/workflows/*.yml and list all workflow files.
2. Parse — Read each file; validate YAML syntax.
3. Audit — Run every check in the checklist below against each file.
4. Cross-check — Run cross-workflow consistency checks.
5. Report — Output a findings table sorted by severity (critical > high > medium > low).
6. Fix offer — For each finding, suggest a concrete fix (diff or instruction).

Audit Checklist

1. YAML Validity

• File parses as valid YAML.
• No duplicate keys at the same level.
• No tabs (GitHub Actions requires spaces).

2. Action Version Currency

Check every uses: line.

Node.js deprecation timeline (reference for findings):

• June 2, 2026: Node 24 becomes default (FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true to opt in early).
• Fall 2026: Node 20 removed entirely from runners.
• Temporary opt-out after June 2: ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true (stops working fall 2026).

3. Security — Script Injection

For every run: block, check for untrusted context expressions used inline:

# DANGEROUS — attacker-controlled input interpreted by shell
run: echo "${{ github.event.issue.title }}"

# SAFE — passed via environment variable
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"

Untrusted contexts (must NEVER appear directly in run: blocks):

• github.event.issue.title / .body
• github.event.pull_request.title / .body
• github.event.comment.body
• github.event.review.body / github.event.review_comment.body
• github.event.commits.*.message
• github.event.head_commit.message / .author.email / .author.name
• github.event.pull_request.head.ref / .head.label / .head.repo.default_branch
• github.head_ref
• github.event.pages.*.page_name

Safe contexts (numeric or system-controlled, OK inline):

• github.event.issue.number, github.event.pull_request.number
• github.repository, github.run_id, github.sha
• github.ref (only on push/tag events, not PR)
• secrets.*, env.*, matrix.*

4. Security — Permissions

5. Security — Auto-merge and Bot Patterns

6. Reliability — Timeouts

7. Reliability — Error Handling

8. Reliability — Concurrency

9. Reliability — Branch Protection Awareness

10. Cross-Workflow Consistency

11. Claude Code Action — Configuration

Reference: anthropics/claude-code-action@v1

Key claude_args flags:

• --model <model-id> — e.g., claude-opus-4-6, claude-sonnet-4-6
• --max-turns <N> — limit conversation turns
• --allowedTools <tool1>,<tool2> — restrict tool access
• --disallowedTools <tool1> — block specific tools
• --system-prompt "..." — custom system prompt

Authentication options:

• anthropic_api_key — direct Anthropic API
• claude_code_oauth_token — Claude Code OAuth (subscription-based)
• use_bedrock: true + OIDC — Amazon Bedrock
• use_vertex: true + OIDC — Google Vertex AI

12. Trigger Hygiene

Report Format

Output a markdown table:

## Workflow Audit Report

| # | Severity | File | Check | Finding | Fix |
|---|----------|------|-------|---------|-----|
| 1 | critical | ci.yml | Action versions | `actions/checkout@v4` — Node 20 deprecated | Upgrade to `@v6` |
| 2 | high | claude.yml | Auto-merge | Enabled for all PRs | Add `if: github.event.pull_request.user.login == 'claude[bot]'` |

After the table, add a Summary line: X critical, Y high, Z medium, W low findings across N workflow files.

Notes

• Do NOT modify workflow files during audit — report only.
• When the user asks to fix findings, apply changes and re-audit to verify.
• For security findings, always explain the attack vector (not just the rule).
• Check .github/workflows/ only — ignore .github/actions/ unless referenced.