Help us learn about your current experience with the documentation. Take the survey.

Manifest reference for AI development principles

The principles sync reads .ai/principles/manifest.yml to determine which principles to generate, which source files each principle is derived from, and how to open the auto-generated merge request.

For the onboarding flow, see AI development principles.

Top-level keys

Key	Type	Required	Description
`auto_mr`	map	Yes	Configuration for the merge request opened by the scheduled sync.
`principles`	map	Yes	Map of principle slug to principle entry. See Principle entry.
`static_entries`	list	No	Manually maintained files included in the agent context-loading skill.

Principle entry

Each key under principles: is a slug. The value is a map with the following keys:

Key	Type	Required	Description
`description`	string	Yes	One-line summary used in the agent routing table. Start with a capital letter. Do not end with a period.
`group`	string	Yes	Group label used to cluster related principles in the routing table. For example: `Database`, `Backend`, `Frontend`.
`sources`	list of maps	Yes	Source documentation files for the principle. See Source entry.
`file_filters`	list of strings	No	Glob patterns that identify which repository paths the principle applies to. The sync uses these to scope drift detection.
`baseline`	string	No	Path to a file containing hand-curated rules. The distiller preserves baseline content verbatim. See Baseline files.
`prerequisite`	boolean	No	When `true`, the routing table marks this principle as a prerequisite for all other principles in the same group and the distiller prepends a note referencing it in every non-prerequisite distilled file in that group. Default: `false`.
`owner_team`	string	No	CODEOWNERS handle of the team that owns the source documentation. The sync groups principles by this value, opens one merge request per team, and routes approval to this team through CODEOWNERS.
`secondary_teams`	list of strings	No	Additional CODEOWNERS handles for source documentation that spans more than one team. Listed as inline code in a “Request a review from” section so the merge request does not notify these groups.
`fallback_ping_team`	boolean	No	Fallback ping behavior when no source-documentation author resolves to a user. When `true` (default), the merge request summary mentions the `owner_team` handle. When `false`, it uses the non-mention team slug so a large group is not notified on every run.
`team_slug`	string	No	Short, URL-safe name used for the per-team branch and merge request title. Defaults to the last path segment of `owner_team`. Set this when the last segment is generic (for example, `approvers`) and would collide across teams.

Source entry

Each item in sources: is a map with the following keys:

Key	Type	Required	Description
`path`	string	Yes	Repository path to the source documentation file, relative to the repository root.
`url`	string	Yes	Canonical URL on `docs.gitlab.com` for the source file. The distilled file links back here so reviewers can verify rules against the published documentation.

Auto-merge request configuration

The auto_mr: map controls how the scheduled sync opens its merge request:

Key	Type	Required	Description
`branch_prefix`	string	Yes	Prefix for source branch names. The sync reuses an open team or tooling branch, or appends the run date when creating one.
`title_template`	string	Yes	Title template for the merge request. Supports `%{date}` interpolation.
`labels`	list of strings	Yes	Labels applied to the merge request.
`remove_source_branch`	boolean	Yes	When `true`, the source branch is deleted after the merge request merges.

Merge request reviewers

Each per-team merge request pings the people who changed the source documentation since the principle was last distilled. The sync queries the GitLab GraphQL API for the commit authors in the range between the previous distillation and the target branch, and mentions the linked GitLab users in the merge request summary. This matches on any confirmed email associated with the account, not only a public one. The sync skips authors that are bot accounts, on a small deny-list of known service accounts, or whose commit email is not linked to any GitLab account.

When no author resolves to a user, the summary falls back to the fallback_ping_team behavior for the owner_team. Approval always routes to the owner_team through CODEOWNERS, so an unavailable author never blocks the merge request.

Static entries

Files listed under static_entries: are referenced from the agent context-loading skill but are not generated by the sync. Use this list for hand-maintained topical modules under .ai/ that are not derived from source documentation.

Key	Type	Required	Description
`description`	string	Yes	Task description that triggers loading. For example, `Git, commits, or branches`.
`path`	string	Yes	Repository path to the file, relative to the repository root.

Examples

Minimal principle entry

principles:
  rest-api:
    description: REST API design and conventions
    group: API
    sources:
      - path: doc/development/api_styleguide.md
        url: https://docs.gitlab.com/development/api_styleguide/

Principle entry with all fields

principles:
  database-migrations:
    description: Database migration patterns and zero-downtime safety
    group: Database
    prerequisite: false
    file_filters:
      - 'db/migrate/**/*.rb'
      - 'db/post_migrate/**/*.rb'
    baseline: .ai/principles/baselines/database-migrations.md
    sources:
      - path: doc/development/migration_style_guide.md
        url: https://docs.gitlab.com/development/migration_style_guide/
      - path: doc/development/database/avoiding_downtime_in_migrations.md
        url: https://docs.gitlab.com/development/database/avoiding_downtime_in_migrations/

Auto-merge request block

auto_mr:
  branch_prefix: docs-sync/principles
  title_template: "Update AI development principles from SSOT (%{date})"
  labels:
    - ai-agent
    - documentation
    - type::maintenance
  remove_source_branch: true

Static entry

static_entries:
  - description: Git, commits, or branches
    path: .ai/git.md

Validation

The distiller validates the manifest at load time and aborts with an error when:

The auto_mr: block is missing or is missing any of its required keys.
Any principle is missing the sources: key, or sources: is empty.

This validation runs at sync time, not at merge time: an invalid manifest entry fails the next scheduled (or manual) sync run rather than blocking the merge request that introduced it.

AI development principles for the onboarding flow.
.ai/principles/manifest.yml for the live manifest.
gems/gitlab-ai-principles-distiller for the gem that consumes the manifest.