Alerting Squad Guidelines

1---
2title: Alerting Squad Guidelines
3description: Alerting-specific patterns and conventions for Grafana
4globs:
5  - 'public/app/features/alerting/**'
6---
7 
8# Alerting Squad - Agent Configuration
9 
10This file provides context for AI agents when working on the Grafana Alerting codebase. It contains alerting-specific patterns and references to Grafana's coding standards.
11 
12## Project Context
13 
14**Location**: `public/app/features/alerting/unified/`
15**Squad**: Alerting
16**Focus**: Frontend development for Grafana's unified alerting system
17**Tech Stack**: React, TypeScript, Redux Toolkit, RTK Query, Emotion, Jest, React Testing Library, MSW
18 
19## Grafana Coding Standards
20 
21**IMPORTANT**: Always follow Grafana's official style guides. Do not duplicate standards here - reference the source files:
22 
23### Required Reading
24 
251. **Frontend Style Guide**: [../../../../../contribute/style-guides/frontend.md](../../../../../contribute/style-guides/frontend.md)
26   - Naming conventions, component patterns, TypeScript, exports
27   - Function declarations for components, callback props with "on" prefix
28 
292. **Testing Guidelines**: [../../../../../contribute/style-guides/testing.md](../../../../../contribute/style-guides/testing.md)
30   - React Testing Library, query priorities, user event setup
31 
323. **Styling Guide**: [../../../../../contribute/style-guides/styling.md](../../../../../contribute/style-guides/styling.md)
33   - Emotion usage, `useStyles2` hook patterns
34 
354. **Redux Framework**: [../../../../../contribute/style-guides/redux.md](../../../../../contribute/style-guides/redux.md)
36   - Redux Toolkit patterns, reducer testing
37 
385. **Alerting Testing Guide**: [./TESTING.md](./TESTING.md)
39   - MSW API mocking, permission mocking, data source setup
40 
41### Alerting-Specific Conventions
42 
43**Use @grafana/alerting Package**:
44 
45- **Always check @grafana/alerting for shared components/hooks** before creating new ones:
46 
47```typescript
48  // Good - Use exported components/hooks from @grafana/alerting
49  import { AlertLabel, alertingMatchers } from '@grafana/alerting';
50 
51  // Check what's available before reimplementing
52```
53 
54**Layout Components**:
55 
56- **Prefer @grafana/ui layout components** over styled divs:
57 
58```typescript
59  // Good - Use Box for simple layout/spacing
60  import { Box } from '@grafana/ui';
61  <Box marginLeft={1}>Content</Box>
62 
63  // Good - Use Stack for flex layouts
64  import { Stack } from '@grafana/ui';
65  <Stack direction="column" gap={2}>
66    <div>Item 1</div>
67    <div>Item 2</div>
68  </Stack>
69 
70  // Avoid - Custom styled divs when layout components exist
71  <div className={styles.wrapper}>Content</div>
72```
73 
74## Alerting Codebase Structure
75 
76### Key Directories
77 
78- `api/` - RTK Query API slices for data fetching
79- `components/` - Feature-specific React components organized by domain
80- `hooks/` - Reusable custom hooks for logic and data fetching
81- `rule-editor/` - Alert rule creation and editing forms
82- `rule-list/` - Alert rules list views (v1 and v2)
83- `state/` - Redux state management and context providers
84- `utils/` - Utility functions and helpers
85- `types/` - TypeScript type definitions
86- `mocks/` - MSW mock server setup for testing
87- `testSetup/` - Test utilities and configuration
88 
89### Component Domains
90 
91- `alert-groups/` - Alert grouping and filtering
92- `contact-points/` - Contact point configuration
93- `notification-policies/` - Notification routing policies
94- `mute-timings/` - Mute timing windows
95- `silences/` - Silence management
96- `receivers/` - Receiver configuration
97- `templates/` - Notification templates
98- `permissions/` - Permission management
99- `settings/` - Alertmanager settings
100 
101## State Management Patterns
102 
103### RTK Query (Primary - Preferred)
104 
105**IMPORTANT**: Our direction is to use RTK Query for data fetching, NOT Redux.
106 
107- API slices in `api/` directory
108- Custom base query in `api/alertingApi.ts`
109- Automatic caching with 2-minute polling: `RULE_LIST_POLL_INTERVAL_MS`
110- Key APIs: `alertRuleApi`, `alertmanagerApi`, `prometheusApi`, `receiversApi`
111 
112**For new features**: Always use RTK Query hooks for data fetching:
113 
114```typescript
115import { useGetAlertRulesQuery } from '../api/alertRuleApi';
116 
117const { data, isLoading, error } = useGetAlertRulesQuery(params);
118```
119 
120### Using Auto-Generated API Clients (`@grafana/api-clients`)
121 
122**IMPORTANT**: When consuming an API endpoint, always prefer the auto-generated clients from `@grafana/api-clients` over creating custom RTK Query endpoints manually. Do not create new RTKQ endpoints by hand — use the generated ones instead.
123 
124The auto-generated clients are available under `@grafana/api-clients/rtkq/<api-group>/<version>` (e.g., `@grafana/api-clients/rtkq/notifications.alerting/v0alpha1`).
125 
126**When the auto-generated client works as-is** — just import and use it directly:
127 
128```typescript
129import { generatedAPI } from '@grafana/api-clients/rtkq/notifications.alerting/v0alpha1';
130 
131const { data } = generatedAPI.useListReceiversQuery(params);
132```
133 
134**When the auto-generated client is incomplete** (e.g., missing request body types), use `enhanceEndpoints` to override the endpoint while still using the generated client as base. This avoids creating a fully manual RTKQ endpoint:
135 
136```typescript
137import { CreateReceiverTestApiArg, generatedAPI } from '@grafana/api-clients/rtkq/notifications.alerting/v0alpha1';
138 
139// Define the missing body type
140interface TestReceiverIntegrationBody {
141  integration: { type: string; settings: Record<string, unknown> };
142  alert: { labels: Record<string, string>; annotations: Record<string, string> };
143}
144 
145// Extend the generated arg with the correct body type
146export interface CreateReceiverTestOverrideArg extends CreateReceiverTestApiArg {
147  body: TestReceiverIntegrationBody;
148}
149 
150// TODO: Remove this override once the auto-generated client includes the request body type
151const enhancedApi = generatedAPI.enhanceEndpoints({
152  endpoints: {
153    createReceiverTest: (endpoint) => {
154      endpoint.query = (queryArg: CreateReceiverTestOverrideArg) => ({
155        url: `/receivers/${queryArg.name}/test`,
156        method: 'POST' as const,
157        body: queryArg.body,
158      });
159    },
160  },
161});
162 
163// Re-export with correct types
164export function useCreateReceiverTestMutation() {
165  const [originalTrigger, state] = enhancedApi.useCreateReceiverTestMutation();
166  const trigger = (arg: CreateReceiverTestOverrideArg) => originalTrigger(arg);
167  return [trigger, state] as const;
168}
169```
170 
171**Key rules**:
172 
1731. Always start from `@grafana/api-clients` — never skip it to write a manual RTKQ endpoint
1742. If the generated client has gaps (missing body, wrong types), use `enhanceEndpoints` to patch it
1753. Mark overrides with a `TODO` comment so they can be removed when the generated client is fixed
1764. Place enhanced API wrappers in the `api/` directory (e.g., `api/testReceiversApi.ts`)
177 
178### Redux Toolkit (Legacy)
179 
180**Avoid for new features** - Use RTK Query instead
181 
182- Legacy reducers exist in `state/reducers/`
183- Use state selectors: `useUnifiedAlertingSelector`
184- Only modify if maintaining existing Redux code
185 
186### Context Providers
187 
188- `AlertmanagerContext` - Alertmanager selection state, for managing Alertmanager entities for a specific Alertmanager data source.
189- `SettingsContext` - Settings state – used in `public/app/features/alerting/unified/components/settings`
190- `WorkbenchContext` - Workbench state used in the alert triage feature `public/app/features/alerting/unified/triage`
191 
192### Forms
193 
194- Use `react-hook-form` (v7) for all forms
195- See `rule-editor/alert-rule-form/` for patterns
196 
197## Alerting-Specific Testing Patterns
198 
199See [./TESTING.md](./TESTING.md) for comprehensive testing guide. Key points:
200 
201### API Mocking with MSW
202 
203**REQUIRED**: Use MSW for all API mocking (not `jest.fn()`) – though it's fine to use this function for unit testing.
204 
205```typescript
206import { mockApi } from '../mockApi';
207 
208// Mock common endpoints
209mockApi.eval(); // for AlertingQueryRunner
210// If helper doesn't exist, add it to mockApi.ts
211```
212 
213**Why MSW?** Forces proper loading state handling, discovers UI issues early
214 
215### Permission Mocking
216 
217**Default: RBAC enabled** (most common user scenario)
218 
219```typescript
220import { enableRBAC, grantUserPermissions } from '../mocks';
221 
222enableRBAC(); // Usually not needed, enabled by default
223grantUserPermissions([AccessControlAction.AlertingRuleRead]);
224```
225 
226### Mock Data Factories
227 
228Located in `mocks.ts`:
229 
230```typescript
231mockDataSource();
232mockPromAlert();
233mockRulerGrafanaRule();
234mockAlertmanagerAlert();
235mockSilence();
236```
237 
238### Data Source Setup
239 
240Located in `testSetup/datasources.ts` for data source mocking patterns
241 
242### Test Data Factories
243 
244**Use factories for creating test data** - Don't manually create objects.
245 
246For Kubernetes APIs and new schemas – use the `@grafana/alerting` package.
247 
248Mock factories are defined in `packages/grafana-alerting/src/grafana/api/notifications/v0alpha1/mocks/fakes`
249MSW handlers in `packages/grafana-alerting/src/grafana/api/notifications/v0alpha1/mocks/handlers`
250 
251And there are "scenarios" that combine the two above. An example of such is `packages/grafana-alerting/src/grafana/contactPoints/components/ContactPointSelector/ContactPointSelector.test.scenario.ts` and is used for integration tests.
252 
253Additionally alerting uses **`alertingFactory`** from `mocks/server/db` for building test data:
254 
255```typescript
256import { alertingFactory } from './mocks/server/db';
257import { mockFolder } from './mocks';
258 
259// Build a single alerting rule
260const alertingRuleBuilder = alertingFactory.ruler.grafana.alertingRule;
261const rule = alertingRuleBuilder.build();
262 
263// Build multiple rules
264const rules = alertingRuleBuilder.buildList(6);
265 
266// Override specific fields
267const customRule = alertingRuleBuilder.build({
268  grafana_alert: { title: 'CPU Alert' },
269  labels: { severity: 'critical' },
270});
271```
272 
273**Common patterns**:
274 
275```typescript
276// Alerting rules
277alertingFactory.ruler.grafana.alertingRule.build();
278alertingFactory.ruler.grafana.alertingRule.buildList(n);
279 
280// Folders
281mockFolder(); // Simple mock function
282 
283// Override fields when building
284alertingRuleBuilder.build({
285  grafana_alert: { title: 'Custom Title' },
286  labels: { key: 'value' },
287});
288```
289 
290**Benefits**:
291 
292- Consistent test data across tests
293- Easy to generate multiple instances with `buildList(n)`
294- Override only the fields you care about
295- Automatic sequencing (e.g., "Alerting rule 1", "Alerting rule 2")
296 
297**Other mock functions** (from `mocks.ts`):
298 
299```typescript
300mockDataSource();
301mockPromAlert();
302mockRulerGrafanaRule();
303mockAlertmanagerAlert();
304mockSilence();
305mockFolder();
306```
307 
308## Alerting-Specific Patterns
309 
310### Feature Toggles & settings
311 
312A full list of features can be found in `pkg/services/featuremgmt/toggles_gen.csv` – focus on feature toggles owned by `@grafana/alerting-squad`.
313 
314```typescript
315import { config } from '@grafana/runtime';
316 
317if (config.featureToggles.alertingTriage) {
318  // Render triage view
319}
320```
321 
322A common configuration setting would be `unifiedAlertingEnabled` which allows a user to configure Grafana without any alerting UI or backend enabled at all.
323 
324### Date/Time Formatting
325 
326Use `dateTimeFormat()` / `dateTimeFormatTimeAgo()` from `@grafana/data` instead of `dateTime().format()` — they respect the user's configured timezone.
327 
328```typescript
329// Good - respects user timezone
330import { dateTimeFormat, dateTimeFormatTimeAgo } from '@grafana/data';
331dateTimeFormat(timestamp);
332dateTimeFormatTimeAgo(timestamp);
333 
334// Bad - ignores user timezone setting
335import { dateTime } from '@grafana/data';
336dateTime(timestamp).format('YYYY-MM-DD HH:mm:ss');
337```
338 
339### Data Source Abstractions
340 
341```typescript
342import { isGrafanaRulerRule } from '../utils/rules';
343 
344if (isGrafanaRulerRule(rule)) {
345  // Grafana-managed
346} else {
347  // External alertmanager
348}
349```
350 
351### Access Control (RBAC)
352 
353```typescript
354import { useAbilities } from '../hooks/useAbilities';
355 
356function Component() {
357  const [_, { can }] = useAbilities();
358  const canCreate = can(AccessControlAction.AlertingRuleCreate);
359 
360  return canCreate ? <CreateButton /> : null;
361}
362```
363 
364### Key Routes
365 
366Defined in `routes.tsx`:
367 
368- `/alerting` - Home
369- `/alerting/list` - Rules list (v1/v2)
370- `/alerting/new/:type?` - Create rule
371- `/alerting/:id/edit` - Edit rule
372- `/alerting/notifications` - Contact points
373- `/alerting/routes` - Notification policies
374 
375### Common Hooks
376 
377```typescript
378useCombinedRuleNamespaces(); // Combines Prometheus + Ruler rules
379useAlertmanagerConfig(); // Fetch alertmanager config
380useFolder(); // Folder operations
381useUnifiedAlertingSelector(); // Redux state – avoid using
382useAbilities(); // Permission checking
383```
384 
385### Link URLs and Navigation
386 
387**IMPORTANT**: Different navigation components require different URL formats.
388 
389#### When to use `createRelativeUrl`
390 
391Use `createRelativeUrl` **only with LinkButton** (and other components that render HTML `<a>` elements):
392 
393```typescript
394import { createRelativeUrl } from '@grafana/data';
395import { LinkButton } from '@grafana/ui';
396 
397// LinkButton renders <a> tag - needs manual subpath prefix
398<LinkButton href={createRelativeUrl('/alerting/list')}>
399  View Rules
400</LinkButton>
401```
402 
403**Why?** LinkButton renders a native HTML anchor element, so it doesn't use React Router. You must manually add the subpath prefix using `createRelativeUrl`.
404 
405#### When NOT to use `createRelativeUrl`
406 
407Do **NOT** use `createRelativeUrl` with:
408 
4091. **locationService** - Automatically adds prefix:
410 
411```typescript
412import { locationService } from '@grafana/runtime';
413 
414// locationService uses react-router history - prefix added automatically
415locationService.push('/alerting/list'); // ✅ Correct - no createRelativeUrl
416locationService.push(createRelativeUrl('/alerting/list')); // ❌ Wrong - double prefix!
417```
418 
4192. **TextLink component** - Automatically adds prefix:
420 
421```typescript
422import { TextLink } from '@grafana/ui';
423 
424// TextLink uses react-router Link - prefix added automatically
425<TextLink href="/alerting/list">View Rules</TextLink> // ✅ Correct
426<TextLink href={createRelativeUrl('/alerting/list')}>View Rules</TextLink> // ❌ Wrong
427```
428 
429#### Summary
430 
431| Component/Service    | Use `createRelativeUrl`? | Reason                                  |
432| -------------------- | ------------------------ | --------------------------------------- |
433| `LinkButton`         | ✅ YES                   | Renders `<a>` tag (native HTML)         |
434| `Button` with `href` | ✅ YES                   | Renders `<a>` tag when href provided    |
435| `locationService`    | ❌ NO                    | Uses react-router history (auto-prefix) |
436| `TextLink`           | ❌ NO                    | Uses react-router Link (auto-prefix)    |
437| React Router `Link`  | ❌ NO                    | React Router component (auto-prefix)    |
438 
439**Rule of thumb**: If it renders a native HTML `<a>` tag, use `createRelativeUrl`. If it uses React Router, don't.
440 
441## Key Libraries
442 
443### Grafana Internal
444 
445- `@grafana/ui` - UI components (Button, Select, Input, etc.)
446- `@grafana/data` - Data models and utilities
447- `@grafana/runtime` - Runtime services (config, backendSrv, locationService)
448- `@grafana/scenes` - Scene framework (Insights/Triage views)
449- `@grafana/e2e-selectors` - Test selectors
450- `@grafana/alerting` - Grafana managed alerting specific package (utility functions, API endpoints, mocks, React components, etc)
451 
452### External
453 
454- `react-hook-form` (v7) - Form state
455- `@reduxjs/toolkit` - Redux + RTK Query
456- `@emotion/css` - Styling
457- `lodash` - Utilities
458- `msw` - API mocking for tests
459 
460## Quick Reference Checklists
461 
462### Creating a New Component
463 
4641. ✅ Create in appropriate `components/` subdirectory
4652. ✅ Use function declaration (not arrow function)
4663. ✅ Add TypeScript props interface (no "I" prefix)
4674. ✅ Use `useStyles2` for styling (Emotion)
4685. ✅ Create colocated test file
4696. ✅ Use MSW for API mocking in tests
4707. ✅ Query with `*ByRole` queries
471 
472### Adding a New API Endpoint
473 
4741. ✅ Check if the endpoint exists in `@grafana/api-clients` — always prefer auto-generated clients
4752. ✅ If the generated client is incomplete, use `enhanceEndpoints` to patch it (see [Using Auto-Generated API Clients](#using-auto-generated-api-clients-grafanaapi-clients))
4763. ✅ Place the wrapper in the `api/` directory
4774. ✅ Add helper to `mockApi.ts` for testing
4785. ✅ Handle loading/error states in UI
4796. ✅ Test with MSW
480 
481### Creating a New Form
482 
4831. ✅ Use `react-hook-form` (v7)
4842. ✅ See `rule-editor/alert-rule-form/` for patterns
4853. ✅ Add validation (schema if needed)
4864. ✅ Handle API submission errors
4875. ✅ Test user interactions with `userEvent`
488 
489### Writing Tests
490 
491Check https://testing-library.com/docs/queries/about/ for what selectors to prefer when using React Testing Library
492 
493- [ ] RBAC enabled by default
494- [ ] MSW for API mocking (not `jest.fn()`)
495- [ ] Loading states tested
496- [ ] Error states tested
497- [ ] User interactions use `userEvent.setup()`
498- [ ] Queries prefer `*ByRole`
499- [ ] Async operations use `await` and `findBy*`
500- [ ] Permissions tested with `grantUserPermissions`
501 
502## Using GitHub CLI for Context
503 
504When working on issues, PRs, or needing repository context, use the GitHub CLI (`gh`) to fetch information directly:
505 
506### Common Commands
507 
508```bash
509# View issue details
510gh issue view &lt;issue-number&gt;
511 
512# View PR details and diff
513gh pr view &lt;pr-number&gt;
514gh pr diff &lt;pr-number&gt;
515 
516# List recent issues
517gh issue list --limit 10
518 
519# List PRs with specific labels
520gh pr list --label &quot;alerting&quot;
521 
522# Search issues
523gh issue list --search &quot;keyword&quot;
524 
525# View PR reviews and comments
526gh pr view &lt;pr-number&gt; --comments
527 
528# Check CI status
529gh pr checks &lt;pr-number&gt;
530 
531# View repository info
532gh repo view
533```
534 
535### When to Use
536 
537- **Understanding issue context**: Fetch issue descriptions, comments, and linked PRs
538- **Reviewing PR changes**: Get diffs, review comments, and CI status
539- **Finding related work**: Search for similar issues or existing implementations
540- **Checking project status**: List open issues/PRs for the alerting team
541 
542### Example Workflow
543 
544```bash
545# Working on issue #12345
546gh issue view 12345
547 
548# Check if there's an existing PR
549gh pr list --search &quot;fixes #12345"
550 
551# Review a related PR
552gh pr view 67890
553gh pr diff 67890
554```
555 
556## Learning from Corrections
557 
558When the user corrects a mistake you made (wrong API, wrong pattern, wrong approach), assess whether the correction represents a recurring pattern worth documenting. If so, propose a concise addition to this AGENTS.md — but do **NOT** apply it without explicit approval.
559 
560Skip proposing an update if the correction is:
561 
562- A one-off or highly context-specific fix
563- Already documented in this file
564- A personal preference rather than a project convention
565 
566## Dependency Security
567 
568- **No new dependencies without explicit approval**: Do NOT run `yarn add` or otherwise introduce new packages. If a task would benefit from a new dependency, stop and ask the user for approval first — explain what package you want, why, and its publish date.
569- **7-day quarantine**: Even with approval, never add a dependency whose latest version was published less than 7 days ago. Check publish date with `npm view <package> time --json` before proposing.
570- **Prefer established packages**: Favor well-known, actively maintained packages. Avoid packages with very few downloads or no recent maintenance.
571- **No postinstall script overrides**: The repo has `enableScripts: false`. Do not add per-package script overrides without approval from @grafana/frontend-ops.
572- **Lock file integrity**: Always use `yarn install --immutable`. Never manually edit `yarn.lock`.
573- **Report suspicious packages**: If a dependency shows signs of compromise (unexpected scripts, obfuscated code, ownership transfer), flag it in the PR and tag @grafana/frontend-ops.
574 
575## Getting Help
576 
577- Check patterns in existing `components/` code
578- Review test examples in `*.test.tsx` files
579- Consult `mockApi.ts` for API mocking
580- See `mocks.ts` for data factories
581- Read [./TESTING.md](./TESTING.md) for testing details
582- Review Grafana style guides (linked at top)
583- Use `gh` CLI to fetch issue/PR context from GitHub
584 
585---
586 
587**Last Updated**: 2026-03-31
588**Maintained By**: Alerting Squad
589