actionlint-pants-plugin

A Pantsbuild plugin that lints GitHub Actions workflow files with actionlint: workflow syntax, ${{ }} expressions, action inputs, runner labels, and the shell scripts in run: steps.

Installation

Add the plugin to pants.toml. Pants ignores dot-directories by default, so .github/ MUST be made visible too:

[GLOBAL]
plugins = ["actionlint-pants-plugin==<version>"]
pants_ignore.add = ["!.github/"]

Declare the workflow targets next to the workflow files:

# .github/workflows/BUILD
github_workflow_sources()

Then run actionlint through the lint goal:

pants lint .github/workflows::   # or `pants lint ::`

How it works

actionlint is downloaded as a static binary; nothing is installed into a Pants resolve. The plugin registers a github_workflow_sources target generator, which yields one github_workflow_source target per *.yml or *.yaml file next to the BUILD file, and a pants lint integration over those targets. For each run Pants:

1. Puts the workflow files, their dependencies and the config file (see below) into a sandbox, together with an empty .git directory: actionlint only reads its config and validates local uses: ./... references inside a git repository, and a sandbox is not one.
2. Downloads shellcheck through Pants' [shellcheck] subsystem and passes it as -shellcheck, so run: steps are checked as they would be with shellcheck on the PATH. Set [actionlint].shellcheck = false to opt out. The pyflakes integration is always disabled, as Pants ships no pyflakes tool.
3. Runs actionlint -color once per batch on the workflow files. The linter fails when actionlint does.

Target fields

Configuration

actionlint reads .github/actionlint.yaml or .github/actionlint.yml from the repository root (reference). Pants includes that file automatically. Point [actionlint].config at a config file elsewhere to pass it as -config-file, which takes precedence over the repository config.

Using a different actionlint version

Add the release's checksums and sizes to known_versions and set version:

[actionlint]
version = "1.7.13"
known_versions.add = [
  "1.7.13|linux_arm64 |<sha256>|<size>",
  "1.7.13|linux_x86_64|<sha256>|<size>",
  "1.7.13|macos_arm64 |<sha256>|<size>",
  "1.7.13|macos_x86_64|<sha256>|<size>",
]

Compute each line with curl -L $URL | tee >(wc -c) >(shasum -a 256) >/dev/null, where $URL is the actionlint_<version>_<os>_<arch>.tar.gz asset of the GitHub release (linux/darwin, amd64/arm64).

Supported versions

Pants loads plugins into its own interpreter, so the plugin requires the Python version Pants runs on.

Releases

Wheels are published to PyPI. Release notes live in the changelog and on the GitHub releases page.

Contributing, Bug Reports and Feature Requests

This plugin lives in the pants-plugin-depot repo. See its CONTRIBUTING.md, or open an issue.