.mate.yml reference

.mate.yml is the per-repository Mate configuration file. Commit it to the repository root; it is read on every webhook that targets the repository. Changes go through your normal MR review process.

The file follows the same schema as the tenant configuration, with these exceptions: bots: is not allowed (only the tenant operator may register GitLab users), policies: is not allowed (rate-limiting and concurrency are tenant-level only), and a small set of repo-only fields are available for agents and triggers.

Note

.mate.yml is read from the branch associated with the current event, not always the default branch. See Branch selection below. The tenant config is always the authority ceiling — a repo file can narrow authorities but never expand them beyond what the tenant allows.

File discovery

Mate fetches a single configured filename — .mate.yml by default — from the repository root. There is no .yaml fallback. The file is fetched fresh on every webhook; there is no cache.

Branch selection

Mate picks the git ref used to fetch .mate.yml in this order:

1. MR-flavored events (mr_assigned, mr_opened, comment_mention on an MR, label_applied on an MR): the MR’s source branch.
2. Pipeline events: the pipeline’s source branch (for MR pipelines) or the pipeline’s ref (for branch pipelines).
3. Issue events and everything else: the project’s default branch.

Because the source branch is user-controlled, a branch .mate.yml can narrow authorities, adjust prompts, or add triggers — but can never escalate beyond the tenant-level authority ceiling.

Top-level structure

version: 1          # optional; if present, must be 1
agents: { ... }     # optional map of agent-name → definition
triggers: [ ... ]   # optional ordered list; repo triggers are evaluated first

All three top-level keys are accepted. Any other key is a validation error and causes the entire config to be rejected.

bots: is explicitly forbidden. Including it produces the error: bots: is not allowed in .mate.yml; only the tenant YAML may declare bots.

policies: is also forbidden — rate-limiting and concurrency (cooldown, concurrency, default_timeout) are tenant-level only. Including policies: in .mate.yml is a validation error.

Agents

Agents in .mate.yml do one of two things:

• Override a tenant-defined agent — same name, field-by-field overlay. Fields you omit inherit from the tenant definition.
• Define a new repo-only agent — must use extends: to name a tenant agent as its base.

See the tenant configuration agent reference for the full field list. The sections below document the repo-only additions.

system_prompt_append

Appends a suffix to the base agent’s system_prompt, separated by a blank line. Use this when you want to add repo-specific instructions without replacing the base prompt entirely.

agents:
  reviewer:
    system_prompt_append: |
      This repository uses Conventional Commits for all commit messages.
      Always check that any suggested commits follow the format.

system_prompt_append is mutually exclusive with system_prompt on the same agent entry. Setting both is a parse error. system_prompt_append is only valid in .mate.yml — using it in the tenant config is also a parse error.

extends

Inherits fields from a named base agent. Required when defining a new agent name that does not exist at tenant level. Optional when overriding an existing tenant agent (the same-named tenant agent is the implicit base when extends: is omitted).

agents:
  repo-security-agent:
    extends: senior-reviewer   # must exist in tenant config
    system_prompt_append: |
      Focus exclusively on security issues in this diff.
    permissions: [read, comment]   # must be a subset of senior-reviewer's permissions

The extends merge is shallow: lists and maps replace whole — nothing concatenates. Cycles (A extends B extends A) are rejected at validation time.

Cross-layer chains resolve correctly: a repo agent that extends a tenant agent that itself extends another tenant agent inherits the full field chain.

Permission subset enforcement

The effective permissions of any repo-defined or repo-overriding agent must be a subset of the base (tenant) agent’s permissions. Attempting to grant an authority the base agent does not have is a merge-time error.

Case	Result
Override existing tenant agent, subset permissions	Accepted
Override existing tenant agent, same permissions	Accepted
Override existing tenant agent, adds new authority	Error: not a subset of base
New agent with extends:, subset permissions	Accepted
New agent with extends:, authority not in base	Error: not a subset of base
New agent without extends:, no matching tenant agent	Error at merge time

Triggers

Triggers in .mate.yml use the same syntax as the tenant triggers reference.

Repo triggers are prepended to the tenant trigger list, so they are evaluated first. That ordering only matters when a repo trigger and a tenant trigger resolve to the same agent for the same event and context: Mate’s dedup identity is (event kind, agent name, context), so the two collapse into one job, and the repo trigger’s job wins that slot because it was evaluated first. A repo trigger that names a genuinely different agent does not replace the tenant trigger at all — both fire, producing an additional job alongside the tenant one. See How many jobs does one event create? for the full model.

In practice, a repo author who wants to redirect an event’s behavior without touching the tenant config keeps the trigger’s agent: name the same as the tenant’s (so the two jobs collapse into one) and instead overrides that agent’s definition — model, prompt, permissions — from .mate.yml. Naming a different agent adds a second job rather than replacing the first.

when: filter

The when: block is accepted for schema compatibility. Unknown keys inside when: are a parse error.

Caution

when: assignee_in is parsed but not currently enforced — the trigger fires regardless of which bot was assigned. Use if: assignee (exact-match string comparison) as the working alternative. See Accepted but not yet enforced in the triggers reference.

triggers:
  # Working alternative to assignee_in: use if: assignee
  - on: mr_assigned
    agent: reviewer
    if:
      assignee: mate-junior

deny: on triggers

The deny: field subtracts authorities from the agent’s effective permission set for this trigger only. It does not affect the agent when triggered from other rules.

triggers:
  - on: mr_opened
    agent: contributor
    deny: [push_branch, open_mr]   # read and comment only for this trigger

See Permissions for the full resolution model.

Policies

.mate.yml may not declare a policies: block — rate-limiting and concurrency are tenant-level only. See Policies in the tenant configuration reference.

Complete example

version: 1

agents:
  # Override the tenant "reviewer" agent with a repo-specific prompt suffix.
  reviewer:
    system_prompt_append: |
      This repository contains a payment processor.
      Flag any change that touches transaction state or customer PII
      as high-severity, regardless of how small the diff appears.

  # A new repo-only agent that narrows down a base agent's permissions.
  docs-writer:
    extends: contributor
    description: "Writes and updates documentation only"
    permissions: [read, comment, push_branch]
    system_prompt_append: |
      You only touch files under docs/ and *.md files at the repo root.
      Never modify source code.

triggers:
  # Collapses onto the tenant's mr_opened trigger (same agent name "reviewer")
  # per the same-agent-collapse rule — this job wins since repo triggers
  # evaluate first. A different agent name here would add a job instead.
  - on: mr_opened
    agent: reviewer
    if:
      target_branch: main
      mr_draft: false

  # Route doc-related issues to the docs-writer agent.
  - on: issue_assigned
    agent: docs-writer
    if:
      assignee: mate-docs

  # Restrict push+open_mr for pipeline failures: comment only.
  - on: pipeline_failed
    agent: reviewer
    deny: [push_branch, open_mr]