Skip to content

.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: policies:, deny: and allowed_users: are not allowed (they are workspace-level only), and a small set of repo-only fields are available for agents. Managed accounts are registered in the console, never in YAML.

Mate fetches .mate.yml from the repository root (only that exact name; .mate.yaml is not read). The file is fetched fresh on every webhook; there is no cache. If a file exists but cannot be fetched, parsed or merged (for example an unknown key or an authority the base agent lacks), the event is rejected with no job and no fallback to the workspace config. A missing file is fine: the workspace config applies alone.

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

  1. MR-flavored events (merge_request events, note events on an MR): the MR’s source branch.
  2. Pipeline events: the MR’s source branch (for MR pipelines) or the pipeline’s ref (for branch pipelines).
  3. Push events: the pushed branch.
  4. Issue events and everything else (tag pushes, jobs, deployments, releases, wiki pages, notes on issues): 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.

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 file to be rejected.

policies: is forbidden — cooldown, concurrency and default_timeout are workspace-level only. allowed_users: is likewise workspace-only and rejected here with a specific error. Including either in .mate.yml is a validation error.

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.

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. A repo system_prompt (without append) replaces the base prompt outright. system_prompt_append is only valid in .mate.yml — using it in the tenant config is also a parse error.

Inherits fields from a named base agent, which must be a workspace agent (a repo agent cannot extend another repo agent). Required when defining a new agent name that does not exist at workspace 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. A repo agent may override description, backend, model, system_prompt, permissions, image, timeout, variables and env. keep_container is not taken from .mate.yml; the workspace value stands. 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.

A repo env: map replaces the workspace agent’s env: map wholesale. If it sets any of ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, OPENROUTER_API_KEY, OPENAI_BASE_URL or OPENAI_API_KEY — or if the repo overrides the agent’s image: — the repo owns the whole LLM configuration for that agent: the workspace LLM key is not injected, and repo-supplied secret values are not stored. This guarantees your workspace key is never sent to an endpoint a repo chose. A repo override must therefore target an endpoint that needs no secret.

The effective permissions of any repo-defined or repo-overriding agent must be a subset of the base agent’s permissions (the same-named workspace agent for an override, the extends: target for a new agent). The workspace deny: list still applies on top. 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 in .mate.yml use the same syntax as the tenant triggers reference.

Repo triggers are placed ahead of the workspace trigger list, so they are evaluated first. Because all matching triggers fire, a repo trigger never replaces a workspace trigger: if both match the same event, both produce a job. The dedup identity includes the agent name, so two triggers naming different agents never collapse. See How many jobs does one event create? for the full model.

To change how an existing workspace trigger behaves for one repository, override the agent’s definition (model, prompt, permissions) in .mate.yml under the same agent name.

when: assignee_in: [<username>, ...] is evaluated for any trigger that carries it and restricts the trigger to the listed managed accounts (it is meaningful on issue and merge_request triggers; events without assignee data never match it). See when: filter.

triggers:
- on: merge_request
assigned: true
agent: reviewer
when:
assignee_in: [mate-junior]

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: merge_request
assigned: true
agent: contributor
deny: [push_branch, open_mr] # read and comment only for this trigger

See Permissions for the full resolution model.

.mate.yml may not declare a policies: block — cooldown, per-project concurrency and the default timeout are workspace-level only. See Policies in the tenant configuration reference.

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:
# Review every MR that asks the account for a review.
- on: merge_request
review_requested: true
agent: reviewer
if:
target_branch: main
mr_draft: false
# Route doc-related issues to the docs-writer agent.
- on: issue
assigned: true
agent: docs-writer
if:
assignee: mate-docs
# Pipeline failures on main: comment only, no code push.
- on: pipeline
status: [failed]
branch: main
account: mate-ci
agent: reviewer
deny: [push_branch, open_mr]