Skip to content

Choose a tag to compare

@github-actions github-actions released this 13 Sep 16:07
· 760 commits to master since this release
Immutable release. Only release title and notes can be modified.
v1.17.0
08bb2c4

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.yml

actionlint 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-untrusted reports explicit write grants on low-trust triggers with access to default-branch caches, including pull_request_target, issue_comment, and workflow_run.
  • cache-call-unrestricted requires an explicit cache ceiling for reusable calls on those triggers.
  • cache-operation reports official actions/cache, actions/cache/save, and actions/cache/restore steps 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: false

Omitted 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 only

Alternatively, 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: true

This 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 test

actionlint 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: true

Previously, 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 test

For 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/Amsterdam

1.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/Amsterdam

Expression 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/actionlint

mise 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.0

Updating 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.

Full changelog