Feature: More zizmor configuration locations

[Zeitsperre]

Pre-submission checks

• I am not reporting a bug (crash, false positive/negative, etc). These must be filed via the bug report template.
• I have looked through the open issues for a duplicate request.

What's the problem this feature will solve?

I just stumbled on this package the other day and really appreciate the work on this! The main problem I have is that the configuration location zizmor.yml is a bit too present for my liking.

Describe the solution you'd like

I would like to see a dotfile .zizmor.yml adopted by default (following other linting/checkers like .flake8, .pre-commit-config.yaml, .yamllint.yml, etc.) to make it easy to ignore this file in my build system (ignore= ".*").

Additional context

Given that this checker looks specifically at GitHub Workflows, I don't see any value in adding the configurations to a language-specific build file (namely pyproject.toml). Being able to drop this information when building a package is important.

[woodruffw]

Thanks for the request @Zeitsperre!

Two considerations:

• ICYMI, you can configure this: if you use the --config option, you can point zizmor at whatever filename you please. For example, zizmor --config .zizmor.yml should work, assuming .zizmor.yml exists.
• By default zizmor looks for both zizmor.yml and .github/zizmor.yml. The latter is inside of a "hidden" directory so that may be more to your taste.

I'm not entirely opposed to supporting .zizmor.yml as an automatically discovered file as well, but I'm hesitant to do so if either of the above is sufficient. My main hesitation there is that discovery rules are mostly irreversible public API commitments, so I'm trying to keep them to a minimum for now.

[Zeitsperre]

Hi @woodruffw, thanks for getting back to me so quickly!

I think for my purposes, I can get by with the --config option (and in fact, I've already set that up as a default in a project template). Personally, I tend to reserve the .github folder for things run by GitHub workflows or that affect the UX of the repo (like templates); I wouldn't think to look there for a pre-commit tooling configuration.

The convenience of being able to implicitly ignore the file in both a build-system (like flit for Python) and in my file browser is a "nice to have".

It isn't uncommon to have multiple (3) locations supported by default with one being a hidden top-level configuration file (e.g. flake8 or ruff) among the options, but perhaps this is more typical of Python projects.

In any case, for my purposes, things are fine as is. I totally understand not wanting to support too many standard locations.

All the best,

[woodruffw]

Hi @woodruffw, thanks for getting back to me so quickly!

Thank you too! I'm glad to hear --config is working for your current use case.

And got it -- I think in that case I'm going to leave things as they are for now, but I'll move this to a discussion item that other folks can chime in on. If there's consistent user interest in this outside of cases that --config can handle, then I'll look at adding it via your work in #321 🙂

[Zeitsperre]

Works perfectly for me. I'll leave the pull request open for the time being, then. Have a good one!

[woodruffw]

Closing for now -- for others who reach this, --config or ZIZMOR_CONFIG is the recommended way to use a non-default configuration location.

[kdeldycke]

I would like to propose to reconsider support of pyproject.toml, as I find it quick clean to have all the project tooling configured in one central place.

Other tooling that are non-Python project have support for them:

• [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 also considering adding support:

• Support taplo configuration in pyproject.toml tamasfe/taplo#603 (Rust)
• Support configuration in [tool.actionlint] section of pyproject.toml rhysd/actionlint#623 (Go)
• 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)

[woodruffw]

Other tooling that are non-Python project have support for them:

From a quick look most of these have some kind of Python connection even if they aren't written in Python themselves (for example Ruff lints Python, even though it happens to be written in Rust).

For zizmor the connection is much more tenuous: it's distributed through PyPI for convenience (and because a lot of Python developers use it), but it has no actual connection to Python packaging or Python project metadata.

Given that I'm pretty hesitant to support pyproject.toml as a configuration source.

(There's also the separate precedence/order issue noted above.)

[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]

In the end I implemented a "tool runner" in repomatic that translates [tool.zizmor] sections from pyproject.toml into zizmor's native YAML config, caches the result, and passes it via --config. No changes needed in zizmor itself.

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

[tool.zizmor]

[tool.zizmor.rules.artipacked]
disable = true

[tool.zizmor.rules.unpinned-uses]
config.policies."*" = "ref-pin"

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

name: CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello"

Then run zizmor via repomatic:

$ uvx repomatic run zizmor -- .
🌈 zizmor v1.23.0
 INFO audit: zizmor: 🌈 completed ./.github/workflows/ci.yaml
warning[excessive-permissions]: overly broad permissions
  --> ./.github/workflows/ci.yaml:8:3
   |
 8 | /   build:
 9 | |     runs-on: ubuntu-latest
10 | |     steps:
11 | |       - uses: actions/checkout@v4
12 | |       - run: echo "Hello"
   | |                          ^
   | |                          |
   | |__________________________this job
   |                            default permissions used due to no permissions: block
   |
   = note: audit confidence → Medium

4 findings (3 suppressed): 0 informational, 0 low, 1 medium, 0 high

As you can see the [tool.zizmor] config is applied, as the artipacked rule is suppressed, unpinned-uses accepts tag-pinned refs like @v4, and only the excessive-permissions finding is 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.