Workflow Linters | GitHub Agentic Workflows
Skip to main content Workflow Linters gh aw lint checks authored AW Markdown and parsed Actions YAML without recompilation. See the CLI reference for options and file discovery. Built-in rules Section titled “Built-in rules” Threat IDs refer to the Compiler Threat Detection Specification . A mapping covers only the checks listed here. Extension rules may omit a threat ID. Built-in rule Threat ID ASTs Checks action-pin CTR-002 AW, Actions Action and reusable-workflow references are literals without expressions, control characters, or whitespace.
Remote references use full commit SHAs; Docker actions use digests. Local paths skip pinning but get format checks. job-timeout CTR-026 AW, Actions Explicit workflow and job timeouts are positive integer literals. Omission is allowed. needs-consistency — AW, Actions needs names existing jobs without self-edges or cycles. Literal accesses name direct dependencies and declared outputs. Prompt references must be available during activation.
Ordering-only dependencies are valid. step-reference — AW, Actions Literal steps accesses name a step ID declared in the same job, including bare if conditions. Output declarations and ordering are not checked. template-injection CTR-006 AW, Actions Known attacker-controlled expressions are not interpolated into executable run or actions/github-script code. Use environment bindings, quoted shell expansions, or process.env instead. workflow-run-scope CTR-021 AW, Actions workflow_run selects workflows and has a positive branch scope, not only wildcard, negated, or empty filters. secret-leak CTR-017 AW, Actions Symbolic secrets do not reach modeled disclosure sinks.
AW-only checks report missing generated execution coverage. otlp-secret-leak CTR-017 AW, Actions Secret-tainted expressions are not exported through OTLP span or resource attributes. Hard-coded credentials and runtime values are not detected. permission-scope CTR-001 AW, Actions Permissions avoid blanket write-all ; OIDC does not use invalid id-token: read . Scoped writes and id-token: write are not violations. version-check CTR-018 AW Authored source does not disable check-for-updates . conditional-import CTR-020 AW Configuration import entries contain no if , even if false or null.
Runtime prompt conditionals are unaffected. private-to-public CTR-031 AW GitHub tool configuration does not opt out of private-to-public flow protections, globally or per server. install-scripts CTR-014 AW Authored Node configuration does not enable dependency install hooks. Other runtimes are not inferred. allowed-labels CTR-015 AW Label allowlists for issue, discussion, discussion-update, and PR creation contain no bare * . network-scope CTR-011 AW Network allowances contain no bare * , including alongside defaults .
Domain wildcards such as *.example.com are allowed. push-target CTR-012 AW A literal wildcard PR-branch push target has an authored title or label constraint. Defers when imports may supply one. tool-scope CTR-003 AW Shell refusal does not conflict with CLI/ gh proxies; min-integrity: none declares shell intent; cache memory avoids repository-wide scope. Defers when imports may supply prerequisites. sandbox-config CTR-004 AW The agent sandbox is not disabled, and internal agent or MCP command, environment, argument, image, or version overrides are not enabled.
Empty overrides are ignored. image-argument CTR-013 AW, Actions Job, service, and authored MCP image operands do not start with - . Registries and computed images are not inspected. checkout-mode CTR-033 AW Repository-list expansion is an explicit boolean. Literal lists need multi mode, a literal non-root prefix, and a scoped allowlist without LFS, submodules, current identity, or wiki expansion. fork-association CTR-034 AW Explicit fork admission uses GitHub’s uppercase author-association enum.
Empty lists and repository wildcards are valid. pull-request-target-roles CTR-008 AW pull_request_target does not admit explicit read or all roles. Checkout disablement and risk acknowledgment do not bypass this. untrusted-roles-detection CTR-005 AW on.roles: all with a trigger untrusted users can fire must not run with threat detection disabled ( threat-detection: false , enabled: false , or engine: false without steps).
Triggers only trusted actors can fire ( schedule , workflow_dispatch , push , merge_group ) are exempt; unknown triggers count as untrusted. A safe_outputs job without a detection job counts as disabled. The finding recommends NVX ( sandbox.agent.runtime: nvx ), which does not exempt the workflow. pull-request-target-checkout CTR-008 AW Checkouts on pull_request_target use supported base-repository or ref forms, or exact allowed literal pairs, without extra fetches.
Omitting checkout is not checkout: false . prompt-expression CTR-010 AW Authored prompt interpolations are valid single-line expressions without blocked JavaScript property traversal. The full context allowlist and imported prompts are not checked. gateway-dispatch-literals — AW Every key and value in on.gateway-dispatch is literal. Strings containing ${{ , including incomplete expressions, are rejected at any depth. safe-output-shell-expansion CTR-009 AW safe-outputs.steps[*].run scripts avoid blocked expansions: parameter transformation, indirect expansion, command substitution, and backticks.
Arithmetic and ordinary variables remain allowed. firewall-ssl-bump CTR-011 AW A nonempty literal --allow-urls in sandbox.agent.args requires --ssl-bump in the same list. Legacy network.firewall blocks require migration, even with ssl-bump: true . custom-job-detection CTR-005 AW, Actions Custom jobs run before agent or after successful detection , including transitive dependencies. Every ` grader-file-io — AW Custom graders.<id>.script JavaScript accesses no filesystem or host capabilities and loads no modules.
Requires the optional native JavaScript parser; without it, a coverage warning is shown. artipacked — AW, Actions actions/checkout explicitly disables credential persistence. Omitted, enabled, or dynamic persistence produces a review warning. Compiler-generated blocks can exempt trusted PR checkouts and credential-cleanup patterns when their paths are statically known and at most 13 directory components deep. cache-poisoning — AW, Actions cache-mode values are literal read , write , write-only , or none ; omit the key for defaults.
Release and tag workflows avoid cache restoration through actions/cache , actions/cache/restore , actions/setup-go , and actions/setup-node . Save-only and lookup-only actions are exempt. Effective cache-mode: write or write-only on events outside GitHub’s write allowlist warns. Job names do not establish publisher trust. excessive-permissions CTR-001 Actions Workflow-wide write grants are moved to the jobs that need them. obfuscation — AW, Actions Runner-interpolated fields avoid literal-only expressions such as ${{ '' }} . bash-case-pattern — AW, Actions Bash case patterns inside $(...) use balanced (pattern) syntax for Bash 3.2 compatibility.
Intentional unquoted glob matching remains allowed. privileged-checkout — AW, Actions Privileged triggers warn on enabled or dynamic allow-unsafe-pr-checkout , PR-head, dispatch, or upstream-head checkout selectors, literal refs/pull/ refs, and direct gh pr checkout or Git calls selecting them. Trusted base checkouts are not flagged. artifact-execution — AW, Actions workflow_run warns when cross-run downloads extract into the workspace or an unknown path, or when later direct execution uses their literal destination.
Privileged custom code Section titled “Privileged custom code” privileged-checkout and artifact-execution warn in strict and non-strict mode, are enabled in the default registry, and are not runtime enforcement. Skipping lint removes their diagnostics; strict pull_request_target policies still apply, and trigger-risk acknowledgment does not disable these checks. privileged-checkout co
The rest of this page is on the live site.