AGENTS.md

1# GitLab Project Guidelines
2 
3This file provides default AI agent instructions for the GitLab project.
4For customization options, see .ai/README.md.
5 
6## Local Overrides
7 
8Read @CLAUDE.local.md
9 
10## Context Loading
11 
12Load the following instruction files based on your current task:
13 
14- When working with **git, commits, or branches**: Read .ai/git.md
15- When working with **merge requests**: Read .ai/merge-requests.md
16- When **reviewing code or giving feedback**: Read .ai/code-review.md
17- When working with **CI/CD pipelines or `.gitlab-ci.yml`**: Read .ai/ci-cd.md
18- Before planning, implementing, OR reviewing code changes (including MR reviews), load the `gitlab-coding-principles` skill. This applies even when `.ai/code-review.md` is also loaded.
19 
20## Always-on rules
21 
22These apply to every task without needing a trigger:
23 
24- **Minimal fix** — apply the smallest change that solves the problem; do not expand scope across layers unless each layer is genuinely load-bearing
25 
26## Project Notes
27 
28- Default branch: `master`
29- GitLab has extensive CI/CD pipelines; be patient with pipeline results
30- Danger bot will comment on MRs with warnings; these are often non-blocking
31- This repository is very large; use targeted searches and glob patterns
32 
33## Fix Pipeline merge requests
34 
35When opening a merge request as part of the Fix Pipeline flow (the title contains `[FixPipeline]`), apply labels based on the source of the run. The `<fix_pipeline_source>` block in your instructions contains exactly one of `merge_request`, `default_branch`, or `branch` — use it to determine which case applies.
36 
37- **`merge_request`**: apply `pipeline::tier-1`. This runs the cheaper tier-1 pipeline instead of the full default pipeline.
38- **`default_branch`**: apply both `pipeline::expedited` and `master:broken`. The expedited label fast-tracks the fix through CI by skipping non-essential jobs; the master:broken label marks the MR as a broken-master fix. Do not apply `pipeline::tier-1` in this case.
39- **`branch`**: apply `pipeline::tier-1`. Same treatment as the `merge_request` case — a fix MR for a non-default branch pipeline failure with no originating MR.
40 
41### Known failures and CI health context
42 
43Before diagnosing a failure, check whether it matches a known active incident. Three sources:
44 
45- [ci-health-incidents](https://gitlab.com/gitlab-org/quality/analytics/ci-health-incidents/-/issues?state=opened&label_name[]=ci-health%3A%3Aactive) — test file failures, failure categories, uncategorized job failures
46- [ci-health-systemic](https://gitlab.com/gitlab-org/quality/analytics/ci-health-systemic/-/issues?state=opened&label_name[]=ci-health%3A%3Aactive) — recurring systemic failures affecting many pipelines
47- [top flaky test files](https://gitlab.com/gitlab-org/quality/test-failure-issues/-/issues?state=opened&label_name[]=automation%3Atop-flaky-test-file&label_name[]=automation%3Abot-authored) — known flaky test files
48 
49Each ci-health incident title names the affected test file, failure category, or job. The flaky test issues title the affected spec file.
50 
51If the failing job or test matches an open issue in any of these:
52 
531. Link to the issue in your response or fix MR description.
542. Use it to guide your approach:
55   - **Infra failure** (`failed_to_pull_image`, `runner_system_failure`, etc.): no code fix is possible. Post a comment with the incident link. Do not open a fix MR.
56   - **Known flaky test**: the failure may be unrelated to the MR. Note this and link the issue, but still check whether the MR changes could have contributed.
57   - **Known failure category** (`docs_outdated`, `rake_outdated_translated_strings`, etc.): likely unrelated to the MR. Post a comment with the incident link rather than attempting a code fix.
58