check-github-workflow

name	check-github-workflow
description	Audits a GitHub Actions workflow YAML file (or a directory under `.github/workflows/`) against 30 deterministic checks (top-level `name:`, permissions, timeouts, concurrency, SHA-pinning for every `uses:`, no `@main`/`@master`/floating refs, `pull_request_target` + PR checkout combo, template injection in `run:`, deprecated commands, secrets-in-top-env, fork-PR secret exposure, harden-runner first, persist-credentials, strict bash, actionlint, zizmor, yamllint, shellcheck on extracted `run:` content) plus seven judgment dimensions. Use when the user wants to "audit a github workflow", "lint my workflow", or "run zizmor on this". Not for composite actions — different rubric.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
argument-hint	[path]
user-invocable	true
references	["../../_shared/references/github-workflow-best-practices.md","references/check-correctness-and-error-handling.md","references/check-maintainability.md","references/check-performance-and-concurrency.md","references/check-permissions-and-secrets-discipline.md","references/check-pinning-and-supply-chain-posture.md","references/check-runtime-safety.md","references/check-trigger-discipline.md"]
license	MIT

Check GitHub Workflow

Audit a GitHub Actions workflow file for structural soundness, safety posture, pinning discipline, and adherence to the authoring rubric. The rubric lives in github-workflow-best-practices.md.

This skill follows the check-skill pattern. Tier-1 detection is in 9 scripts emitting JSON envelopes via _common.py (30 rule_ids total). Tier-2 has 7 judgment dimensions read inline by the primary agent. No Tier-3 cross-entity rule for this skill (workflows audit individually).

When to use

Also fires when the user phrases the request as:

• "check this workflow"
• "review my github actions"
• "is this workflow safe"

Workflow

1. Scope

Read $ARGUMENTS. Resolve to a .github/workflows/*.yml file or a directory containing workflows. Confirm scope aloud.

2. Tier-1 Deterministic Checks

Invoke 9 detection scripts:

SCRIPTS="${SKILL_DIR}/scripts"
TARGETS="$ARGUMENTS"

python3 "$SCRIPTS/check_secrets.py"     $TARGETS   # 1 rule:  secret (FAIL)
python3 "$SCRIPTS/check_structure.py"   $TARGETS   # 9 rules: workflow-name, job-name, step-name, permissions-top, timeout-minutes, defaults-shell, concurrency-group, concurrency-deploy, id-kebab
python3 "$SCRIPTS/check_pinning.py"     $TARGETS   # 5 rules: sha-pin-third-party, sha-pin-first-party, no-floating-ref, docker-tag, runner-pin-deploy
python3 "$SCRIPTS/check_safety.py"      $TARGETS   # 9 rules: pr-target-checkout, template-injection, deprecated-cmds, workflow-env-secrets, fork-pr-secrets, self-hosted-public-pr, strict-bash, persist-credentials, harden-runner-first
python3 "$SCRIPTS/check_shellcheck.py"  $TARGETS   # 1 rule:  shellcheck-run; inapplicable when shellcheck absent
python3 "$SCRIPTS/check_size.py"        $TARGETS   # 2 rules: run-block-size, workflow-size
bash    "$SCRIPTS/check_actionlint.sh"  $TARGETS   # 1 rule:  actionlint; inapplicable when absent
bash    "$SCRIPTS/check_zizmor.sh"      $TARGETS   # 1 rule:  zizmor; inapplicable when absent
bash    "$SCRIPTS/check_yamllint.sh"    $TARGETS   # 1 rule:  yaml-valid; inapplicable when absent

Each script emits a JSON array of envelopes. recommended_changes is canonical — copy through verbatim.

Script-to-rules map (30 Tier-1 rule_ids):

Script	rule_ids	Severity
check_secrets.py	secret	fail
check_structure.py	permissions-top, timeout-minutes, concurrency-deploy	fail
check_structure.py	workflow-name, job-name, step-name, defaults-shell, concurrency-group, id-kebab	warn
check_pinning.py	sha-pin-third-party, no-floating-ref, docker-tag	fail
check_pinning.py	sha-pin-first-party, runner-pin-deploy	warn
check_safety.py	pr-target-checkout, template-injection, deprecated-cmds, workflow-env-secrets, fork-pr-secrets, self-hosted-public-pr	fail
check_safety.py	strict-bash, persist-credentials, harden-runner-first	warn
check_shellcheck.py	shellcheck-run	warn
check_size.py	run-block-size, workflow-size	warn
check_actionlint.sh	actionlint	warn
check_zizmor.sh	zizmor	warn
check_yamllint.sh	yaml-valid	warn

The previously-INFO harden-runner-first, run-block-size, and workflow-size rules are remapped to warn (the pattern has no INFO).

Tier-2 exclusion list. Any FAIL in secret, permissions-top, timeout-minutes, concurrency-deploy, sha-pin-third-party, no-floating-ref, docker-tag, pr-target-checkout, template-injection, deprecated-cmds, workflow-env-secrets, fork-pr-secrets, or self-hosted-public-pr excludes the workflow from Tier-2.

Missing-tool degradation. check_shellcheck.py, check_actionlint.sh, check_zizmor.sh, and check_yamllint.sh emit envelopes with overall_status: inapplicable and exit 0 when their respective tools are absent. Other scripts continue.

3. Tier-2 Judgment Dimensions

For each workflow that passed the Tier-2 exclusion gate, evaluate against the 7 judgment rules at references/check-*.md:

File	Dimension	Severity
check-trigger-discipline.md	D1 — triggers scoped to actual need; pull_request_target justified	warn
check-permissions-and-secrets-discipline.md	D2 — least-privilege permissions; secrets scoped narrowly	warn
check-pinning-and-supply-chain-posture.md	D3 — pin discipline; Dependabot governance	warn
check-runtime-safety.md	D4 — strict bash; harden-runner; no shell injection	warn
check-correctness-and-error-handling.md	D5 — if: guards meaningful; failure-handling explicit	warn
check-performance-and-concurrency.md	D6 — concurrency posture deliberate; caches deterministic	warn
check-maintainability.md	D7 — names are developer-facing; long blocks extracted	warn

Evaluator policy: see check-skill-pattern.md §Evaluator policy. Read all 7 rule files first, then evaluate the workflow in one LLM call.

4. Tier-3

No Tier-3 cross-entity rule for this skill. Workflows audit individually; cross-workflow concerns (duplicated logic, naming collisions across .github/workflows/) are handled by /build:check-skill for the workflow author's wider repo, not by this skill.

5. Report

Merge findings from Tier-1 + Tier-2 into a unified table:

| Tier | rule_id | Location | Status | Reasoning |
|------|---------|----------|--------|-----------|

Sort: fail before warn before inapplicable; Tier-1 before Tier-2. Each Recommendation: line copies through recommended_changes verbatim.

6. Opt-In Repair Loop

Ask once: "Apply fixes? Enter y (all), n (skip), or comma-separated numbers."

For each selected finding:

• Direct edit — SHA pin, permissions block, timeout-minutes, harden-runner step. Show diff; write on confirmation.
• Routed to another skill — substantial rewrites → /build:build-github-workflow.
• Tier-2 judgment — ask the user; rewrite the section; show diff.

After each fix, re-run the relevant Tier-1 script.

Anti-Pattern Guards

1. Per-dimension LLM call. Collapse into one locked-rubric call per workflow.
2. LLM-evaluating format compliance. YAML shape, pin syntax, permissions presence — handle deterministically.
3. Ambiguous compliance reported as PASS. Surface as WARN.
4. Bulk-applying fixes. Per-finding confirmation required.
5. Re-evaluating scripted rules in Tier-2. Trust the pass envelope.
6. Suppressing the inapplicable envelope. When actionlint/zizmor/yamllint/shellcheck is absent, the corresponding envelope emits inapplicable — surface them.
7. Embellishing scripts' recommended_changes. Copy through; do not paraphrase.

Key Instructions

• Run Tier-1 deterministic checks first; gate LLM evaluation on structural validity.
• The 4 wrapper scripts (actionlint, zizmor, yamllint, shellcheck) gracefully degrade to inapplicable when their tools are absent.
• Recovery: read-only outside the Repair Loop.

Handoff

Chainable to: /build:build-github-workflow (rebuild non-compliant workflows from scratch).