AGENTS.md

Guidance for AI coding agents working in this repository. Keep this file concise and current. For end‑user docs, see README.md and https://prometheus.io/docs/alerting/alertmanager/.

Project overview

Alertmanager handles alerts sent by clients such as Prometheus. It deduplicates, groups, routes, silences, and inhibits alerts, and dispatches them to receiver integrations (email, PagerDuty, Slack, webhook, etc.).

• Language: Go (see go.mod for the required version, currently go 1.26).
• Frontend (legacy): Elm app under ui/app/ (Node version pinned in .nvmrc).
• Frontend (new): React + TypeScript + Mantine under ui/mantine-ui/.
• API: OpenAPI v2 spec in api/v2/openapi.yaml; Go server/client/models are generated via scripts/swagger.sh.
• Module path: github.com/prometheus/alertmanager.

Repository layout

Top‑level packages worth knowing:

• cmd/alertmanager/ — main binary entry point (main.go); thin wrapper that parses flags and calls app.
• app/ — embeddable Alertmanager runtime extracted from cmd/alertmanager. Owns the process lifecycle (New/Start/Stop/Reload/Run), subsystem wiring (setup), config-reload subgraph (reloader), listeners and Options. Lets tests and other binaries run Alertmanager in‑process. See https://github.com/prometheus/alertmanager/issues/406.
• cmd/amtool/ — CLI for interacting with the Alertmanager API.
• api/ — HTTP API. api/v2/ is the active REST API; api/connect/ is the experimental ConnectRPC API mounted under /api/; api/v1_deprecation_router.go only returns deprecation responses.
• cli/ — amtool command implementations.
• cluster/ — HA gossip clustering (memberlist-based).
• config/ — YAML config parsing, validation, secrets, coordinator.
• dispatch/ — routing tree, alert grouping, dispatcher loop.
• inhibit/ — inhibition rule engine.
• mute/, silence/, timeinterval/ — muting, silences (with nflog), time‑based mutes.
• nflog/ — notification log (persisted dedup state).
• notify/ — notification pipeline plus one subpackage per integration (slack, pagerduty, email, webhook, discord, jira, msteams, msteamsv2, opsgenie, pushover, rocketchat, sns, telegram, victorops, webex, wechat, mattermost, incidentio).
• template/ — notification templating (Go templates + default email template). template/email.tmpl is generated from template/email.html.
• provider/mem/ — in‑memory alert provider (the only provider).
• store/ — alert/silence store helpers.
• types/ — core domain types (Alert, Silence, Matcher, ...).
• matcher/ — label matcher parsing (used by routes, silences, inhibitions).
• featurecontrol/ — feature flags wired through --enable-feature.
• limit/, httpserver/, tracing/ — server plumbing.
• ui/web.go — embeds the built UI assets and serves them.
• examples/, doc/examples/ — example configs and HA setups.
• test/with_api_v2/ and test/cli/ — integration/e2e tests.

Generated code (do not hand‑edit):

• api/v2/{models,restapi,client}/ — regenerated by scripts/swagger.sh from api/v2/openapi.yaml.
• ui/app/src/Data/ — Elm types generated from the OpenAPI spec.
• template/email.tmpl — generated from template/email.html via template/Makefile.
• cluster/clusterpb/cluster.pb.go, nflog/nflogpb/nflog.pb.go, silence/silencepb/silence.pb.go — regenerate via scripts/genproto.sh if the .proto schema must change.

Common commands

Builds and tests are driven by the shared Makefile.common plus the repo‑specific Makefile.

• make build — build alertmanager and amtool (also builds Elm UI assets).
• make build-all — UI assets + regenerated API + binaries.
• make build BINARIES=amtool — build a single binary.
• make assets — regenerate Elm Data types and template/email.tmpl.
• make apiv2 — regenerate api/v2/{models,restapi,client} from api/v2/openapi.yaml (runs scripts/swagger.sh; needs Docker).
• make test — full Go test suite (go test ./...) plus UI tests.
• make test-short (via Makefile.common) — go test -short ./....
• make lint — golangci-lint run (version pinned in Makefile.common) plus UI lint.
• make common-format — go fmt + golangci-lint fmt (gofumpt + goimports with local prefix github.com/prometheus/alertmanager).
• make fuzz-config — short fuzz run over ./config.
• make clean — remove generated API code, generated email template, and UI build output.

Run a single Go test package or test:

go test ./notify/slack/...
go test ./dispatch -run TestDispatcherRace -v

Run the UI dev servers directly when iterating on the frontend:

# Legacy Elm UI
cd ui/app && make build         # see ui/app/CONTRIBUTING.md
# New Mantine UI
cd ui/mantine-ui && npm install && npm run dev

Run Alertmanager locally:

./alertmanager --config.file=doc/examples/simple.yml
# multi-node HA via Procfile (requires goreman):
goreman start

Conventions

• Follow the lint rules in .golangci.yml. Notable forbidden imports (enforced by depguard):
  • Use github.com/stretchr/testify/require, not .../testify/assert.
  • Use github.com/go-kit/log, not github.com/go-kit/kit/log.
  • Use the standard errors/fmt, not github.com/pkg/errors.
• Formatting: gofumpt + goimports with local prefix github.com/prometheus/alertmanager. Run make common-format before committing.
• Comments on exported identifiers must be full sentences ending in a period (godot lint).
• Logging uses log/slog (sloglint). Prefer structured key/value logging.
• Errors: wrap with fmt.Errorf("...: %w", err) and check with errors.Is/errors.As (errorlint).
• Keep package‑level documentation up to date (revive: package-comments).
• Tests live next to the code as *_test.go. Larger integration tests live under test/. The notify/test package provides shared testing helpers for notifier integrations.
• Tests use the standard testing package with testify/require, t.Run subtests, and t.Cleanup.
• Unit tests run with t.Parallel(); only the e2e tests stay sequential because API v2 router construction mutates global go-openapi state.

When changing the API

1. Edit api/v2/openapi.yaml.
2. Run make apiv2 to regenerate api/v2/{models,restapi,client} (requires Docker; see scripts/swagger.sh).
3. Run make assets so the Elm UI's Data types stay in sync.
4. Update api/v2/api.go handlers for any new operations.
5. Run make test lint.

Do not hand‑edit generated files under api/v2/models, api/v2/restapi, api/v2/client, or ui/app/src/Data.

When adding or modifying a notifier

• Each integration lives in its own package under notify/<name>/.
• Add config in notify/<name>/config.go (struct, validation, defaults) and wire it into config/config.go receivers.
• Register the notifier in cmd/alertmanager/main.go where receivers are built.
• Add unit tests in the notifier package; reuse helpers from notify/test/.
• Update template/default.tmpl only if you are introducing new default templates.

When touching configuration

• config/config.go owns top‑level YAML parsing; field changes typically need:
  • Struct + yaml tags.
  • UnmarshalYAML validation.
  • Defaults in DefaultGlobalConfig / receiver defaults.
  • Tests in config/config_test.go, possibly testdata/ fixtures.
• Validate behaviour with make fuzz-config for parser changes.

CI expectations

GitHub Actions and CircleCI run build, tests, and golangci-lint. Before pushing:

make common-format
make lint
make test

If you regenerate API code or UI data, commit the regenerated files alongside the source changes.

Things to avoid

• Don't reintroduce APIv1; it was removed in 0.27.0. The only thing left under api/v1_deprecation_router.go is a deprecation responder.
• Don't bypass the notification pipeline (notify/notify.go) — new stages should be added as notify.Stage implementations.
• Don't add new top‑level dependencies without checking .golangci.yml depguard rules and go.mod minimums.
• Don't commit generated artifacts unless the corresponding source (openapi.yaml, email.html, etc.) changed in the same commit.

Useful references

• Architecture diagram: doc/arch.svg (source doc/arch.xml).
• Example configs: doc/examples/simple.yml, examples/ha/, examples/webhook/.
• Maintainers and ownership: MAINTAINERS.md, CODEOWNERS.
• Release process: RELEASE.md.
• UI contributing guide: ui/app/CONTRIBUTING.md.