feat: allow to fetch alerts by labels [DX-5105]

[Tofel]

• watch and single-step check can now select alerts by labels instead of names: --include-labels team=bcm,env=stage, optionally refined with --exclude-labels severity=info. Matches are exact; label selection cannot be combined with --alerts or --folder, and is refused with --in. A selection that matches no rules exits 2.

[github-actions]

👋 Tofel, thanks for creating this pull request!

To help reviewers, please consider creating future PRs as drafts first. This allows you to self-review and make any final changes before notifying the team.

Once you're ready, you can mark it as "Ready for review" to request feedback. Thanks!

[github-actions]

📊 API Diff Results

No changes detected for module github.com/smartcontractkit/chainlink-testing-framework/grafana-alertcheck

View full report

[Copilot]

Copilot review overview

🟡 Changes recommended

Unsupported excluded rules can bypass fail-closed validation, and the CLI rejects a matcher supported by the selection layer.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Allow selecting labels with empty values · New
• Check unsupported kinds before applying exclusions · New
• Update quickstart readiness text for label-based selection · New

What changed in this PR

Adds exact label-based alert selection to watch and single-step check.

Changes:

• Parses rule labels and adds include/exclude matching.
• Integrates label flags with validation and alert resolution.
• Adds tests and documentation.

File	Description
grafana-alertcheck/​README.md	Documents label selection.
grafana-alertcheck/​internal/​gate/​watch.go	Resolves watched alerts by labels.
grafana-alertcheck/​internal/​gate/​watch_test.go	Tests label-based watch behavior.
grafana-alertcheck/​internal/​gate/​parse_ruler.go	Parses rule labels.
grafana-alertcheck/​internal/​gate/​parse_ruler_test.go	Tests label parsing.
grafana-alertcheck/​internal/​gate/​labels.go	Implements matching and validation.
grafana-alertcheck/​internal/​gate/​labels_test.go	Tests matching semantics.
grafana-alertcheck/​internal/​gate/​check.go	Adds label selection to checks.
grafana-alertcheck/​internal/​gate/​check_test.go	Tests label-based checks.
grafana-alertcheck/​docs/​reference/​cli.md	Documents flags and constraints.
grafana-alertcheck/​docs/​index.md	Updates quickstart guidance.
grafana-alertcheck/​docs/​architecture.md	Describes alert-set resolution.
grafana-alertcheck/​cmd/​watch.go	Parses watch label flags.
grafana-alertcheck/​cmd/​watch_test.go	Tests watch flag validation.
grafana-alertcheck/​cmd/​common.go	Adds shared flags and pair parsing.
grafana-alertcheck/​cmd/​common_test.go	Tests label-pair parsing.
grafana-alertcheck/​cmd/​check.go	Parses check label flags.
grafana-alertcheck/​cmd/​check_test.go	Tests check flag validation.
grafana-alertcheck/​.changeset/​v0.1.4.md	Records the feature release note.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The CLI and reference synopses advertise flag combinations that runtime validation rejects.

Review effort: Balanced
Findings: None

Resolved since last review (3)

• Check unsupported kinds before applying exclusions
• Allow selecting labels with empty values
• Update quickstart readiness text for label-based selection

Previously missed (3)

In code that hasn't changed since last review

Scope dependent flags to their valid selection branches

grafana-alertcheck/​cmd/​check.go:19

The synopsis places --exclude-labels and --folder outside the selection alternatives, so --help advertises invalid combinations such as --alerts ... --exclude-labels ... and --include-labels ... --folder ..., both of which validation rejects. Scope each dependent flag to its valid branch.

Scope dependent flags to their valid selection branches

grafana-alertcheck/​cmd/​watch.go:16

The synopsis places --exclude-labels and --folder outside the selection alternatives, so --help advertises invalid combinations such as --alerts ... --exclude-labels ... and --include-labels ... --folder ..., both of which validation rejects. Scope --folder to the alert-name branch and --exclude-labels to the label branch.

Nest folder and exclusion flags under valid selection branches

grafana-alertcheck/​docs/​reference/​cli.md:30

This synopsis currently presents --exclude-labels and --folder as valid with either selection mode, although the documented and implemented constraints reject exclusions without label inclusion and reject folders with labels. Group these flags under the branch where each is accepted.

This issue also appears on line 69 of the same file.