review-agentic-workflows

# Review Agentic Workflows Use this skill when asked to review `.github/workflows/*.md` agentic workflows or their generated `.lock.yml` outputs. Reference workflow authoring skill guidance at: https://raw.githubusercontent.com/github/gh-aw/main/.github/skills/agentic-workflows/SKILL.md ## Goals 1. Produce a security-first review of workflow changes. 2. Compile workflows with validation and security scanners. 3. Flag suspicious changes that weaken protections. 4. Use run history (`logs`/`audit`) when available to find optimization opportunities. ## Agent ownership The agent performs setup, source and runtime-dependency inspection, independent single-reviewer coordination, compilation/scanners, evidence collection, finding resolution and cleanup. Do not give the user a technical preflight checklist to execute. Report concrete blockers and request only authorization or decisions the agent cannot supply. For debugging and live-test gates, follow the [shared security-review guidance](../../aw/debug-security-review.md); the agent prepares the evidence for human validation rather than asking the user to conduct the review. Require exactly one read-only security-review agent per reviewed revision. Resolve coverage questions with that reviewer; do not require parallel judges, majority votes or a tie-breaker. Follow the shared [single-reviewer rules](../../aw/debug-security-review.md#single-reviewer). The user may explicitly authorize live debugging for the current session rather than approve each run. Record the grant and agreed scope/bounds; reuse it for in-scope revisions only after the agent repeats the required technical review. Any compiler security warning invalidates session approval immediately, even if later fixed: resolve it, re-review, and obtain fresh explicit authorization. Follow the shared [session authorization rules](../../aw/debug-security-review.md#session-authorization); a request to update this skill is not itself a session-wide execution grant. Workflow registration/activation and secret presence, validity, or expiry are runtime readiness checks, not pre-dispatch review gates. Do not require workflow or secret inventories, organization-admin access, or proof of usable credentials before an otherwise authorized run. Dispatch and the workflow's startup/authentication checks establish readiness; report their actual failures without automatic retries or enabling workflows. Continue to review declared credential flows, authorized destinations, permissions, and redaction without retrieving secret values. Missing readiness metadata alone is not a security finding or an UNKNOWN safety verdict. ## Self-contained setup (do not assume environment is ready) ### Step 0) Verify CLI availability Run from the repository root: ```bash if gh aw --help >/dev/null 2>&1; then echo "gh aw is installed" else if [ -f ./install-gh-aw.sh ]; then echo "gh aw is missing. The agent must run the install step before continuing:" echo " bash ./install-gh-aw.sh" echo "The agent must then verify:" echo " gh aw --help" else echo "gh aw is missing and ./install-gh-aw.sh is not present in this checkout." fi return 1 2>/dev/null || exit 1 fi ``` ## Review workflow ### 1) Scope the review Run this scope check in the review step: ```bash BASE_REF="${BASE_REF:-origin/main}" if git rev-parse --verify "$BASE_REF" >/dev/null 2>&1; then git diff --name-only "$BASE_REF...HEAD" -- .github/workflows/ else git diff --name-only -- .github/workflows/ fi ``` If source `.md` files changed, treat generated `.lock.yml` drift as part of the review. ### 2) Compile with validation + security tools For changed workflows, run strict compilation with validators: ```bash gh aw compile --strict --actionlint --zizmor --poutine --runner-guard --yamllint --shellcheck ``` If `gh aw` extension is unavailable but local binary exists: ```bash ./gh-aw compile --strict --actionlint --zizmor --poutine --runner-guard --yamllint --shellcheck ``` For debug/dry-run reviews, the agent runs `gh aw compile WORKFLOW --dry-run`, adding available scanners as required by the shared guidance. Do not combine `--dry-run` with `--no-emit`: emitted locks are part of the evidence. A disposable checkout is optional. Running in the current checkout and reverting only compiler-generated changes is permitted after snapshotting all affected files, preserving diagnostic outputs, and checking for concurrent edits. Restore pre-existing user changes exactly; never use a broad worktree reset. See the [snapshot/restore rules](../../aw/debug-security-review.md#compile-only-validation). Fail review on compilation errors or High/Critical security findings unless explicitly justified. ### 3) Enforce security best practices Require and verify: - least-privilege `permissions:` (no `write-all` without explicit rationale) - pinned third-party actions by full commit SHA - safe handling of untrusted GitHub event data (no direct template injection into shell) - explicit `safe-outputs` limits (`max`, constrained event/action sets) - no broadening of network/tool access without justification - no integrity downgrades (for example lower `min-integrity`) ### 4) Detect suspicious weakening changes Treat these as suspicious until proven safe: - permission expansion (especially new `write` scopes or global writes) - relaxed security controls (`strict: false`, reduced guardrails, disabled scans) - larger write blast radius (`safe-outputs` limits removed or sharply increased) - reduced provenance controls (unpinning actions, mutable refs) - wider external access (new unrestricted network domains/ecosystems) - prompt or script edits that reintroduce command/template injection risk Use targeted diffs and call out before/after impact. ### 5) Audit history and optimize (when run data exists) If workflow run IDs/URLs are available, audit them: ```bash gh aw audit <run-id-or-url> gh aw logs --start-date -14d --workflow-name <workflow-name> ``` Look for optimization opportunities: - high token/cost usage - repeated retries/tool failures - long-running steps or bottleneck jobs - unnecessary MCP/tool invocations - firewall denials causing retries or wasted turns Recommend minimal, safe optimizations that keep or improve security posture. ## Review output contract Show an annotated overview of changed authored `.md` files, excluding generated `.lock.yml` diffs from the overview. Link source lines, describe before/after behavior, and explain the security impact of each relevant change in plain language. Include preserved controls and unresolved evidence, not just findings. Keep generated locks in the execution-review evidence. Follow the shared [annotated overview contract](../../aw/debug-security-review.md#annotated-markdown-change-overview). Always provide a short user-visible result sentence for each security review and dry-run attempt, including failed, blocked, or unavailable checks. State the artifact/scope, outcome, what was actually checked, and any material finding or coverage gap. Do not leave results only in logs, artifacts, or subagent replies. Keep security-review and dry-run results separate; neither implies live execution or authorization. Follow the shared [review result](../../aw/debug-security-review.md#user-visible-result) and [dry-run result](../../aw/debug-agentic-workflow.md#user-visible-dry-run-result) rules. Return findings in three sections: 1. **Security regressions (must-fix)** — high-confidence weakening changes. 2. **Validation/scanner results** — compile and tool outcomes. 3. **Optimization opportunities** — optional improvements backed by logs/audit evidence. Each finding should include severity, file(s), rationale, and a concrete remediation direction.