amlint

Semantic linter for Prometheus Alertmanager configs.

amtool check-config validates syntax. amlint validates semantics: will alerts actually reach a receiver, does the inhibition rule do anything, are there unreachable routing branches? These are the bugs that burn teams — config is valid, alerts silently vanish.

Why

Alertmanager configs are YAML routing trees with inhibition rules and receivers. The most painful mistakes are syntactically valid:

• route references a receiver that doesn't exist → alerts are dropped
• inhibition without equal → silences unrelated alerts, you think it's quiet, there's actually a fire
• catch-all branch before specific ones → specific branches are unreachable
• match_re that doesn't compile
• group_by that doesn't behave the way you think

amtool won't catch any of this. amlint will.

Install

pip install amlint

Or with Docker (no Python required):

docker run --rm -v $(pwd):/cfg ghcr.io/danikdanik2013/amlint check /cfg/alertmanager.yml

Usage

amlint check alertmanager.yml
amlint check prod.yml staging.yml           # multiple files
cat alertmanager.yml | amlint check -       # stdin
amlint check alertmanager.yml --strict      # WARN also exits non-zero
amlint check alertmanager.yml --format json
amlint check alertmanager.yml --format sarif > results.sarif  # GitHub Code Scanning
amlint check alertmanager.yml --ignore empty-receiver,unused-receiver
amlint check alertmanager.yml --only undefined-receiver,bad-regex  # run only these checks
amlint check alertmanager.yml --exit-zero   # always exits 0, just show findings
amlint diff old.yml new.yml                 # show what changed
amlint tree alertmanager.yml                # visualize the route tree, issues inline
amlint init > alertmanager.yml              # generate minimal valid config
amlint list                                 # all check codes with level + description
amlint explain undefined-receiver           # detailed explanation + examples

Project config — .amlint.yml or pyproject.toml [tool.amlint]:

# .amlint.yml
ignore:
  - empty-receiver
strict: true
severity:
  unused-receiver: error   # upgrade info → error

# pyproject.toml
[tool.amlint]
ignore = ["empty-receiver"]
strict = true

Shell completions (bash/zsh):

pip install "amlint[completions]"
eval "$(register-python-argcomplete amlint)"  # add to ~/.zshrc or ~/.bashrc

Example output:

  ERROR  Route references receiver 'pager-team' which is not defined in receivers. Alerts matched here will be dropped.
  ↳ route.routes[1]  [undefined-receiver]

  WARN   Catch-all route (no matchers) with continue:false will intercept all alerts — 2 subsequent sibling(s) are unreachable.
  ↳ route.routes[0]  [unreachable-route]

  2 error · 3 warn · 1 info

Exit code 1 on ERROR — ready for CI. --strict makes WARN block too.

CI example

# .github/workflows/lint.yml
- name: Lint Alertmanager config
  run: amlint check alertmanager.yml --strict

As a GitHub Action

- uses: actions/checkout@v7
- uses: danikdanik2013/amlint@v0.2.0
  with:
    config-path: alertmanager.yml
    strict: true

No pip install step needed. Supports --ignore/--only via inputs and optional SARIF upload for PR annotations — see the GitHub Action docs.

Checks

Run amlint explain <code> for detailed description and examples of any check.

Tests

python3 -m pytest test_linter.py -v

License

MIT