.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.
File discovery
Section titled “File discovery”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.
Branch selection
Section titled “Branch selection”Mate picks the git ref used to fetch .mate.yml in this order:
- MR-flavored events (
merge_requestevents,noteevents on an MR): the MR’s source branch. - Pipeline events: the MR’s source branch (for MR pipelines) or the pipeline’s ref (for branch pipelines).
- Push events: the pushed branch.
- 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.
Top-level structure
Section titled “Top-level structure”version: 1 # optional; if present, must be 1agents: { ... } # optional map of agent-name → definitiontriggers: [ ... ] # optional ordered list; repo triggers are evaluated firstAll 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
Section titled “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
Section titled “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. 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.
extends
Section titled “extends”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 permissionsThe 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.
LLM credentials in a repo env:
Section titled “LLM credentials in a repo env:”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.
Permission subset enforcement
Section titled “Permission subset enforcement”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
Section titled “Triggers”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: filter
Section titled “when: filter”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]deny: on triggers
Section titled “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: merge_request assigned: true agent: contributor deny: [push_branch, open_mr] # read and comment only for this triggerSee Permissions for the full resolution model.
Policies
Section titled “Policies”.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.
Complete example
Section titled “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: # 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]