Repository navigation
actionlint 1.17.0 checks explicit cache access controls and enables cache safety
policies by default. It also adds checks informed by GitHub's schemas and runner
code. Valid expression-built matrices can pass without spurious errors, newer
workflow fields are recognized, and malformed schedules and action metadata
receive additional checks. The release adds installation options through the aqua
registry and mise.
Upgrade note: the new policies can make previously clean workflows exit with status 1, including repositories without a configuration file. Existing opt-in policies retain their defaults.
Make cache access explicit
GitHub's cache-mode controls cache access independently of token permissions:
| Mode | Restore | Save |
|---|---|---|
read |
Yes | No |
write |
Yes | Yes |
write-only |
No | Yes |
none |
No | No |
Set it on the workflow or an individual job. Job settings override workflow settings; omission retains GitHub's trigger-dependent defaults. For example, give a reusable workflow a read-only ceiling:
on: pull_request_target
cache-mode: read
jobs:
report:
uses: $/.github/workflows/report.ymlactionlint follows nested local reusable calls and checks their explicit declarations against the caller's limit. Diagnostics preserve the original ./ or $/ reference. Missing or malformed callees are reported consistently regardless of file analysis order. (#163, #164)
Catch unsafe grants and ineffective cache steps
Three policies now run automatically:
cache-write-untrustedreports explicit write grants on low-trust triggers with access to default-branch caches, includingpull_request_target,issue_comment, andworkflow_run.cache-call-unrestrictedrequires an explicit cache ceiling for reusable calls on those triggers.cache-operationreports officialactions/cache,actions/cache/save, andactions/cache/restoresteps whose operations an explicit mode disables. Caller-imposed limits are followed through nested local workflows, including parallel child steps.
GitHub skips forbidden cache operations without failing the job. The operation check makes ineffective steps visible. The combined actions/cache action remains useful under read or write-only, where one operation is still available. Remote workflow bodies, wrappers, and package-manager caching options are not inspected. (#165)
For example, this job explicitly disables the operation its cache step requests:
jobs:
build:
runs-on: ubuntu-latest
cache-mode: read
steps:
- uses: actions/cache/save@v6
with:
path: .cache
key: build-${{ github.sha }}It now receives a cache-operation diagnostic. If the job should only restore a cache, use actions/cache/restore. If it really must save, review the trigger and grant the appropriate write access. The same mismatch is detected when the save lives inside a local reusable workflow and the caller supplies the read ceiling.
Configure policies and reviewed exceptions
Disable individual checks in .github/actionlint.yaml:
policy:
cache-write-untrusted: false
cache-call-unrestricted: false
cache-operation: falseOmitted or null policy values retain the enabled defaults. For a reviewed exception, place an exact rule ID and a reason on the reported line:
cache-mode: write # actionlint:ignore cache-write-untrusted -- jobs execute reviewed default-branch code onlyAlternatively, put # actionlint:ignore-next-line cache-write-untrusted -- reviewed reason immediately above it. These directives affect a physical line and support only the three cache policies.
Repositories can prohibit inline exceptions:
policy:
disallow-suppressions: trueThis reports the prohibited comment and retains the original violation. A mapping can select rules and choose report: all, suppression, or violation. See policy configuration. (#165)
Give expression-built workflows the checks they deserve
A workflow assembled with expressions should still benefit from linting. Previously, a whole strategy expression was rejected as a scalar where a mapping was expected. The resulting empty matrix type then produced another error for a perfectly valid matrix.os reference.
This complete workflow passes in 1.17.0:
on: push
jobs:
test:
strategy: ${{ fromJSON('{"matrix":{"os":["ubuntu-latest","windows-latest"]}}') }}
runs-on: ${{ matrix.os }}
steps:
- run: echo testactionlint now understands the evaluated structure and infers each job's selected os value. Case-insensitive property handling also preserves the matrix when the JSON uses Matrix instead of matrix.
The work extends to supported whole-object expressions for runs-on, job defaults.run, containers, services, environments, concurrency, snapshots, and step with. When values are statically known, actionlint checks their required fields, property names, nested types, and value constraints. Values only available at runtime remain deferred.
For example, an expression does not make an invalid concurrency combination valid:
concurrency:
group: build
queue: ${{ 'max' }}
cancel-in-progress: truePreviously, this was rejected simply because queue contained an expression. Now the expression is understood and the diagnostic explains the actual conflict: queue: max cannot be combined with cancel-in-progress: true. Known whole-map expressions receive the same check, including differently cased JSON keys.
Other refinements catch nonpositive or fractional max-parallel values, empty runner-label arrays, malformed snapshot version globs, and invalid elements inside expression-built collections. Interpolated strings retain their surrounding text: environment: pre-${{ '' }} is not mistaken for an empty environment name.
Use newer workflow fields without fighting the linter
Workflow descriptions and job cancellation timeouts are now supported. Both were reported as unexpected keys in 1.16.1:
description: Build and test the project
on: push
jobs:
test:
runs-on: ubuntu-latest
cancel-timeout-minutes: 2.5
steps:
- run: echo testFor cancel-timeout-minutes, this is support for a field present in GitHub's runner schema and parser fixtures. GitHub's public workflow syntax reference does not document this setting, and its cancellation reference describes a five-minute cancellation timeout. This release validates the field's numeric type and expression contexts. A live GitHub-hosted probe subsequently confirmed that values of 1 and 2 minutes are honored after cancellation: GitHub marked the jobs finished after 60 and 120 seconds, with runner shutdown signals arriving a few seconds later. The test used long-running always() cleanup steps; other values and runner environments were not tested. Jobs calling reusable workflows are kept distinct from jobs with their own steps: combining uses with fields such as services, snapshot, or cancellation timeouts no longer causes misleading recursive callee diagnostics.
Several smaller compatibility fixes make everyday YAML less surprising:
| Workflow feature | What changes in 1.17.0 |
|---|---|
image_version |
Recognizes created, ready, and deleted activity types, plus scalar or sequence names and versions filters. |
| Stacked pull requests | Accepts the stacked activity type for pull_request and pull_request_target. |
| Disabled services | Accepts image: '', GitHub's way to disable a service, instead of reporting an empty-string error. |
| Manual choice inputs | Accepts an empty choice option and matching empty default. |
| Schedule timezones | Accepts UTC aliases such as UTC and Universal; rejects machine-local Local. |
| YAML booleans | Decodes True and TRUE correctly instead of retaining them as false. |
Catch missing checks before GitHub does
The audit also found invalid workflows that previously passed. Each schedule entry must have its own cron; a valid first entry no longer hides a broken second one:
on:
schedule:
- cron: '0 0 * * *'
- timezone: Europe/Amsterdam1.17.0 reports "cron" is missing in element of "schedule" section at the second entry. Put timezone alongside the cron it belongs to:
on:
schedule:
- cron: '0 0 * * *'
timezone: Europe/AmsterdamExpression coverage is more complete too. Snapshot image names and versions were previously skipped; they now receive syntax, type, and context checks. Snapshot conditions can resolve legitimate step outputs. Matrix include expressions check the actual included entry. Static required flags reject expressions, function argument limits follow the runner, and excessive expression nesting is diagnosed.
Look deeper inside local actions
The action-manifest audit covers Docker, JavaScript, and composite action structures using generated constraints from GitHub's runner schema. Referenced local actions now receive stronger checks for output declarations, Docker args and env, required fields, cross-runtime properties, composite step shapes, and expressions.
For example, with expects a mapping. In a composite action, adding an expression to a string does not turn it into one:
runs:
using: composite
steps:
- uses: actions/cache/restore@v6
with: prefix-${{ inputs.cache-key }}That interpolated string is now rejected. Supply individual inputs in a mapping instead:
with:
path: .cache
key: prefix-${{ inputs.cache-key }}A sole mapping-valued expression is supported where the runner allows it; interpolation and whole-map assignment have different meanings. Conversely, workflow steps passing a dynamic whole with mapping no longer receive invented missing-required-input errors for keys only known at evaluation time.
The audit fixes false positives as well: valid Docker lifecycle conditions are accepted, and an entrypoint inside a container image is no longer required to exist in the source checkout. Composite step IDs now catch duplicates case-insensitively, reserved prefixes, and invalid identifiers.
These checks use data shipped with the binary. Linting does not download schemas or fetch arbitrary remote actions. The schema audit and its workflow, expression, and action reports document the authorities and remaining compatibility boundaries. (#164)
The fork is now in the aqua registry
The new kjanat/actionlint registry entry installs this fork's release binaries using metadata for SHA-256 checksums and GitHub artifact attestations. With an initialized aqua.yaml and a standard registry version containing aquaproj/aqua-registry#60566, add it with:
aqua g -i kjanat/actionlintmise can use that same registry through its built-in aqua backend, without installing aqua itself:
mise use aqua:kjanat/[email protected]Use a mise registry snapshot containing the new entry. It is included in the mise 2026.9.7 release PR; mise 2026.9.6 can opt into current registry data with registry_floating = true. The installation guide explains that setting and the available backends.
Prefer a different route? Choose one of mise's other three backends:
# Prebuilt GitHub release binary; independent of aqua registry snapshots
mise use github:kjanat/[email protected]
# npm launcher and platform binary; requires Node.js
mise use 'npm:@kjanat/[email protected]'
# Build from source with Go
mise use go:actionlint.kjanat.dev/cmd/[email protected]The full identifiers matter: mise's short actionlint name selects upstream packages. (#168)
Pin the installer as well as the binary
Download-script examples now pin the script to an immutable commit. The separate version argument selects the binary:
bash <(curl -fsSL https://raw.githubusercontent.com/kjanat/actionlint/662318dd6bbd9c0c120e35b03168bc1be69bf428/scripts/download-actionlint.bash) 1.17.0Updating the binary version no longer silently changes the installer you execute. (#168)
Release SBOMs also gain dependency license information resolved from remote Go module sources. Unknown SPDX fields remain NOASSERTION; missing copyright or download-location data is not invented. The SBOM documentation explains those boundaries. (#167)
Upgrade through your usual channel
Release archives, SHA-256 checksums, and SBOMs are attached below. The fork also ships through these channels:
| Channel | Install or upgrade |
|---|---|
| Homebrew, existing installation | brew upgrade --cask kjanat/tap/actionlint |
| Scoop, bucket already configured | scoop update actionlint |
| Arch Linux / AUR, prebuilt binary | paru -S actionlint-kjanat-bin |
| Arch Linux / AUR, source build | paru -S actionlint-kjanat |
| npm, project dependency | npm install --save-dev @kjanat/[email protected] |
| npm, one-off run | npx @kjanat/[email protected] --help |
| Go | go install actionlint.kjanat.dev/cmd/[email protected] |
| Nix, one-off run | nix run github:kjanat/actionlint/v1.17.0 -- -version |
| Docker / GHCR | docker pull ghcr.io/kjanat/actionlint:1.17.0 |
| Docker Hub | docker pull kjanat/actionlint:1.17.0 |
For aqua and mise, use the examples above. Package-manager commands without an explicit version select the version currently offered by that channel. The installation guide includes first-time setup, external-linter requirements, community integrations, and pending distribution proposals.
For the GitHub Action, select this release in your workflow:
- uses: kjanat/[email protected]The moving v1 and v1.17 action tags are updated too. Repositories pinning action commits or pre-commit revisions should update those pins deliberately.
On your first run after upgrading, review the new cache diagnostics. Set the access your jobs need, or record a narrow, reasoned exception. The new defaults are there to make that decision visible.