Support configuration in `[tool.actionlint]` section of `pyproject.toml`

[kdeldycke]

A lot of non-Python projects are supporting reading their own configuration from pyproject.toml, in a [tool.something] section.

I think it would be cool to have actionlint source its configuration from a [tool.actionlint] section in pyproject.toml.

Exemple:

• [tool.ruff]: https://docs.astral.sh/ruff/configuration/#configuring-ruff (Rust)
• [tool.typos]: https://github.com/crate-ci/typos/blob/master/docs/reference.md (Rust)
• [tool.uv]: https://docs.astral.sh/uv/concepts/configuration-files/ (Rust)
• [tool.ty]: https://docs.astral.sh/ty/ (Rust)
• [tool.maturin]: https://www.maturin.rs/config (Rust)
• [tool.pyright]: https://github.com/microsoft/pyright/blob/main/docs/configuration.md (TypeScript)
• [tool.tombi]: https://tombi-toml.github.io/tombi/docs/configuration/ (Rust)
• [tool.rumdl]: https://github.com/rvben/rumdl (Rust)
• [tool.lychee]: Support for pyproject.toml (and cargo.toml) lycheeverse/lychee#1930 (Rust)

Other tools are considering adding support:

• https://github.com/orgs/zizmorcore/discussions/322#discussioncomment-15919620 (Rust)
• Support taplo configuration in pyproject.toml tamasfe/taplo#603 (Rust)
• Support configuration in `[tool.biome]` section of `pyproject.toml` biomejs/biome#9239 (Rust)
• Support configuration in [tool.shfmt] section of pyproject.toml mvdan/sh#1268 (Go)
• Support configuration from pyproject.toml gitleaks/gitleaks#2066 (Go)

[kdeldycke]

Just to keep track of the support landscape, lychee just added support for [tool.*] in pyproject.toml, as well as Cargo.toml and package.json in the upcoming v0.24 release. See: lycheeverse/lychee#1930 (comment) and lycheeverse/lychee#2104

As for the "precedence/order issue", here is my benchmarking of existing tools:

Looking at other projects, a dedicated configuration file wins over pyproject.toml. In which case it is completely ignored and not merged at all.

Examples of strict precedence:

• Ruff: .ruff.toml > ruff.toml > pyproject.toml (source)
• Uv: uv.toml > pyproject.toml (source)
• Typos: either typos.toml / _typos.toml / .typos.toml, then > Cargo.toml > pyproject.toml (source)

I guess the reason for the strict no-merge policy is to avoid confusion and surprises: only one source of configuration.

As for the dedicated file precedence, it feels like a file at the root of a repository, named after your tool, is way more visible and explicit than a section in pyproject.toml.

As for my personal preference, I like tool-dedicated sections in pyproject.toml to keep the root of my repository clean. And review my tools configurations altogether in a centralized place. Because more often that not, I need to tweak the configuration of tools and coordinate them so they can play nice with each others.

[kdeldycke]

I implemented a "tool runner" in repomatic that translates [tool.actionlint] sections from pyproject.toml into actionlint's native YAML config. Since actionlint has no --config flag, repomatic writes the translated config to .github/actionlint.yaml before the run and cleans it up afterwards. No changes needed in actionlint itself.

So now you can have a pyproject.toml that looks like:

[tool.actionlint.self-hosted-runner]
labels = ["my-custom-runner"]

With a workflow in .github/workflows/ci.yaml:

name: CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: [self-hosted, my-custom-runner]
    steps:
      - uses: actions/checkout@v4
      - run: echo ${{ github.event.pull_request.body }}
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - run: echo "deployed"

Without configuration, actionlint reports two findings:

$ actionlint .github/workflows/ci.yaml
.github/workflows/ci.yaml:9:28: label "my-custom-runner" is unknown. available labels are "windows-latest", "windows-latest-8-cores", "windows-2025", "windows-2025-vs2026", "windows-2022", "windows-11-arm", "ubuntu-slim", "ubuntu-latest", "ubuntu-latest-4-cores", "ubuntu-latest-8-cores", "ubuntu-latest-16-cores", "ubuntu-24.04", "ubuntu-24.04-arm", "ubuntu-22.04", "ubuntu-22.04-arm", "macos-latest", "macos-latest-xlarge", "macos-latest-large", "macos-26-intel", "macos-26-xlarge", "macos-26-large", "macos-26", "macos-15-intel", "macos-15-xlarge", "macos-15-large", "macos-15", "macos-14-xlarge", "macos-14-large", "macos-14", "self-hosted", "x64", "arm", "arm64", "linux", "macos", "windows". if it is a custom label for self-hosted runner, set list of labels in actionlint.yaml config file [runner-label]
  |
9 |     runs-on: [self-hosted, my-custom-runner]
  |                            ^~~~~~~~~~~~~~~~~
.github/workflows/ci.yaml:12:23: "github.event.pull_request.body" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/reference/security/secure-use#good-practices-for-mitigating-script-injection-attacks for more details [expression]
   |
12 |       - run: echo ${{ github.event.pull_request.body }}
   |                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Running via repomatic picks up the [tool.actionlint] config:

$ uvx repomatic run actionlint
warning: actionlint: wrote translated [tool.actionlint] to repo at /private/tmp/claude/actionlint-demo/.github/actionlint.yaml (level 2). This tool has no --config flag; the file will be removed after the run.
.github/workflows/ci.yaml:12:23: "github.event.pull_request.body" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/reference/security/secure-use#good-practices-for-mitigating-script-injection-attacks for more details [expression]
   |
12 |       - run: echo ${{ github.event.pull_request.body }}
   |                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The custom runner label is now recognized and the [runner-label] finding is suppressed, while the [expression] injection warning is still reported.

This bridges the gap for Python projects that want to centralize all tool configuration in pyproject.toml without requiring native support from each tool. The same translation works for other tools like zizmor, gitleaks, biome, shfmt, and others.