Note: for pre-commit hooks I recommend officially supported hooks: See docs: https://github.com/rhysd/actionlint/blob/main/docs/usage.md#pre-commit

actionlint-py

A python wrapper to provide a pip-installable actionlint binary.

Internally this package provides a convenient way to download the pre-built actionlint binary for your particular platform.

Installation

pip install actionlint-py

Usage

After installation, the actionlint binary should be available in your environment (or actionlint.exe on windows). Remember to add you Scripts folder to PATH.

As a pre-commit hook

See pre-commit for introduction.

I recommend using officially supported pre-commit hooks from actionlint itself See docs: https://github.com/rhysd/actionlint/blob/main/docs/usage.md#pre-commit

Use this repo if you can not use officially supported hooks (docker, golang, system) and you are fine with python pip wrapper.

Sample .pre-commit-config.yaml using pip as package manager:

- repo: https://github.com/Mateusz-Grzelinski/actionlint-py
  rev: v1.7.12.24
  hooks:
    - id: actionlint
      additional_dependencies: [ pyflakes>=3.0.1, shellcheck-py>=0.9.0.5 ]
      # actionlint has built in support for pyflakes and shellcheck, sadly they will not be auto updated. Check https://pypi.org/project/actionlint-py/ for latest version. Alternatively:
      # args: [-shellcheck=/path/shellcheck -pyflakes=/path/pyflakes]
      # note - invalid path in arguments will fail silently

Because actionlint-py is available as source distribution, pip build system will fetch binary from (public) github. It might cause problems with corporate proxy. In case of problems try this semi-manual setup that respects your pip.ini:

- repo: local
  hooks:
    - id: actionlint
      name: actionlint
      description: Lint GitHub workflows with actionlint
      additional_dependencies: [ actionlint-py ]
      #additional_dependencies: [actionlint-py==1.7.12.24]
      # safer, but pre-commit autoupdate will not work
      # note: the pip versioning scheme is different from actionlint binary: not "v1.7.12" but "1.7.12.24" (last number is build system version)
      entry: actionlint
      #args: [-ignore "*.set-output. was depracated.*"]
      language: python
      types: [ "yaml" ]
      files: "^.github/workflows/"

Alternative methods of running actionlint

As pre-commit hooks

See official docs for pre-commit integration

- repo: https://github.com/rhysd/actionlint
  rev: v1.7.12
  hooks:
    - id: actionlint
    # - id: actionlint-docker
    # - id: actionlint-system

Use as github action step

Use directly in github action, see official docs for github action integration:

name: Lint GitHub Actions workflows
on: [ push, pull_request ]

jobs:
  actionlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Download actionlint
        id: get_actionlint
        run: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
        shell: bash
      - name: Check workflow files
        run: ${{ steps.get_actionlint.outputs.executable }} -color
        shell: bash

Or using docker:

name: Lint GitHub Actions workflows
on: [ push, pull_request ]

jobs:
  actionlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Check workflow files
        uses: docker://rhysd/actionlint:latest
        with:
          args: -color

Development

Development of wrapper and releasing new version: see README-DEV.md

Roadmap

• Add actionlint hook as docker
  • support shellcheck-py in docker image
  • auto update docker version in .pre-commit-hooks.yaml when using _custom_build/auto_update_main.py
• add shellcheck-py as dependency (or at least document)
• Update tag in readme in github action when releasing new version
• Upload also binary distribution, not only source distribution
• Add unit tests to build system

See README-DEV.md for more TODOs.

Won't do unless asked:

• support all platforms that actionlint supports (like freebsd)