Skip to content

Tenant configuration

The workspace configuration is the YAML you edit under Agents & triggers in the Mate console (a visual editor for agents and triggers, plus a YAML tab on the same draft). It applies to every repository in your workspace. Repositories may overlay it with a .mate.yml file; the tenant config is always the hard ceiling for what any repository can do.

The workspace config and .mate.yml share the same schema. This page is the canonical reference for all shared fields. The .mate.yml reference documents the repo-only additions (system_prompt_append, extends restrictions).

version: 1 # optional; if present, must be 1
allowed_users: [<username>, ...] # optional, who may trigger Mate
deny: [<authority>, ...] # optional, tenant-wide blanket deny
agents: { ... } # map of agent-name → definition
triggers: [ ... ] # list; every matching trigger fires (see Triggers reference)
policies: { ... } # optional

Unknown top-level keys are a validation error. Managed accounts are registered in the console (Managed accounts), not in this YAML.

Optional list of GitLab usernames (letters, digits, _, -, .; no duplicates, case-insensitive). When non-empty, only events initiated by these users start jobs. Your managed accounts always pass, so agent-to-agent chains keep working; an event with no identifiable sender is rejected. A rejected event creates no job and posts no GitLab comment. Absent or empty means anyone who can trigger a managed account may. Workspace-only: .mate.yml may not set it.

allowed_users: [alice, bob]

Optional list of authorities to remove from every agent’s effective permission set across the entire tenant, for every trigger. An authority listed here cannot be granted by any agent or trigger configuration. Typical uses: compliance mandates, incident response, or a per-tenant kill switch. Ingest honors the key when it is present in the stored workspace config; the console editor’s validation currently reports it as an unknown top-level key, so it cannot be saved from the console.

deny:
- push_branch
- merge

Unknown authority strings in deny: are a validation error.

The agents: block is a map from agent name to agent definition. The name is a free-form string used to reference the agent from a trigger’s agent: field.

agents:
reviewer:
description: "Reviews MRs for correctness and style"
backend: claude-code
model: anthropic/claude-sonnet-5.5
system_prompt: |
You are a senior code reviewer. Focus on correctness,
readability, and obvious security issues. Be concise.
permissions: [read, comment]
timeout: 30m
Field Required Type Description
backend yes string LLM CLI adapter: claude-code, codex, omp or opencode. See Backends.
model yes string Model ID in your provider’s naming, e.g. anthropic/claude-opus-5.5 (OpenRouter) or claude-opus-5-5 (Anthropic). Never validated by Mate.
system_prompt yes* string The agent’s system prompt, inline only. This is where the agent’s workflow lives (how it branches, reviews, merges, splits work); Mate’s own per-job prompt only describes the event, the checkout and how working through GitLab works, and adds no process rules. The repository’s own docs (README, CONTRIBUTING, AGENTS.md) are read as well. system_prompt_append is rejected in the workspace config (it exists only in .mate.yml).
permissions yes list of authorities Non-empty list of authority values. Unknown values are rejected.
description no string Free-text note for your own reference. Informational only.
image no string Docker image override. When set, skips the devcontainer cascade and uses this image directly.
timeout no Go duration Per-job time limit for this agent, e.g. 30m, 1h. When absent, policies.default_timeout applies; when that is absent too, 1 hour.
extends no string Name of another agent to inherit fields from. See Inheritance.
env no map Extra environment variables for the agent container. See Environment variables.
variables no map Repository clone strategy using GitLab CI names: GIT_DEPTH (non-negative integer, commits; 0 = full history; default 1), GIT_SUBMODULE_STRATEGY (none default, normal, recursive), GIT_SUBMODULE_DEPTH (non-negative integer, 0 = full; default: same as GIT_DEPTH). Other keys and invalid values are rejected. A repository’s .mate.yml may set them too (the map replaces the workspace one whole). Submodules are skipped, with a note in the job log, when the clone credential is not a per-job scoped token (the master-token passthrough mode used by some on-prem setups).
keep_container no bool When true, the container is not removed after the job finishes. Effective only in on-prem (direct Docker) deployments; no-op on the hosted service. Not overridable from .mate.yml.

* system_prompt is required unless the agent uses extends: to inherit one from a base agent and does not override it.

All agent keys are enumerated above. Unknown keys anywhere in an agent definition are a validation error.

Backend Talks to Notes
claude-code Anthropic API (also via OpenRouter’s Anthropic-compatible endpoint) The primary backend.
codex OpenAI Responses API Needs a provider that speaks the Responses API: OpenAI, OpenRouter, or a compatible endpoint.
omp OpenAI chat completions, or Anthropic Works with any OpenAI-compatible endpoint (Mistral, Scaleway, OpenRouter, …).
opencode OpenAI chat completions, or Anthropic Same provider support as omp.

Any other value is rejected when the config is loaded. Your workspace LLM key must be compatible with the backend; see Models and BYOK.

The model ID, written the way your provider names it. For example, via OpenRouter:

  • anthropic/claude-opus-5.5
  • anthropic/claude-sonnet-5.5
  • anthropic/claude-haiku-5.5

and with an Anthropic key, the bare ID (claude-sonnet-5-5). Mate is provider-neutral: it only checks that model is not empty. It does not check the ID, so a wrong ID surfaces as a provider error when the job runs. Lighter models cost less per job; heavier models handle more complex tasks.

A non-empty list of authorities the agent is allowed to use. See Permissions for the full authority reference and how the effective set is computed.

permissions: [read, comment, push_branch, open_mr]

extends: names another agent whose fields the current agent inherits. The merge is shallow: each field is taken from the child agent if set, otherwise from the parent. Lists and maps replace whole — nothing is concatenated or merged element-by-element.

agents:
base:
backend: claude-code
model: anthropic/claude-sonnet-5.5
system_prompt: |
You are a senior engineer at this company.
permissions: [read, comment, push_branch, open_mr]
junior:
extends: base
model: anthropic/claude-haiku-5.5 # override model only
permissions: [read, comment] # narrower than base — OK
senior:
extends: base
model: anthropic/claude-opus-5.5 # override model only
# inherits base permissions unchanged

Inheritance cycles (A extends B extends A) are rejected at validation time.

The env: block injects additional environment variables into the agent container, for tool configuration or any other runtime value the agent needs.

env:
FOO: "bar"

You normally do not need env: for LLM access: the workspace LLM key you add in the console is injected for every agent that carries no credential of its own, as described in Models and BYOK.

Container CPU and memory are driven by your plan, not by per-agent configuration. The resources: key that existed in earlier versions has been removed; including it is a validation error. On Shared and Dedicated plans each job gets 1 vCPU and 2 GiB of memory.

The triggers: block is a list, evaluated in YAML order. Every trigger whose predicates match fires — Mate does not stop at the first match. See How many jobs does one event create? for the full model, including the one case where two matches collapse into a single job.

See Triggers for the complete trigger reference, including all event types, filters, if: matcher vocabulary, and evaluation semantics.

triggers:
- on: merge_request
review_requested: true
agent: reviewer
if:
target_branch: main
mr_draft: false

The policies: block controls rate-limiting, per-project concurrency and the default time limit.

policies:
cooldown: 5m
concurrency:
group/repoA: 1
group/repoB: 5
default_timeout: 1h
Field Type Description
cooldown Go duration Minimum gap between job starts on the same repository; events queue and dispatch as the window clears. While a cooldown is set, a repository also runs at most one job at a time. Prevents comment-loop spirals.
concurrency map of project path to integer Optional per-project caps on simultaneous jobs (each an integer of at least 1; keys are group/project paths, case-insensitive duplicates rejected). Projects not listed are unrestricted; the tenant total is always bounded by your plan’s mates. A plain number (the former tenant-wide form) is rejected with an error saying policies.concurrency is now a map of project path to cap.
default_timeout Go duration Used for any agent that does not set its own timeout. Without it, 1 hour.

There is no budget key (removed; it is rejected as unknown) and no daily job cap. Mate has no LLM spend cap of its own: you bring your own key, so set spend limits at your LLM provider.

Durations are Go duration strings: 30s, 5m, 1h30m. Unknown keys in policies: are a validation error.

version: 1
agents:
reviewer:
description: "Reviews MRs for correctness and style"
backend: claude-code
model: anthropic/claude-sonnet-5.5
system_prompt: |
You are a senior code reviewer. Review the diff carefully.
Focus on correctness, readability, and obvious security issues.
Post your findings as a single comment. Be concise.
permissions: [read, comment]
fixer:
extends: reviewer
description: "Implements issues and opens MRs"
model: anthropic/claude-opus-5.5
system_prompt: |
You are a careful contributor. Implement the issue's requirements
with the smallest reasonable change, then open an MR for review.
permissions: [read, comment, push_branch, open_mr]
ci-assistant:
backend: claude-code
model: anthropic/claude-sonnet-5.5
system_prompt: |
You are a CI expert. Diagnose the failing pipeline and push a fix.
permissions: [read, comment, push_branch, touch_ci]
timeout: 45m
triggers:
- on: merge_request
review_requested: true
agent: reviewer
- on: issue
assigned: true
agent: fixer
- on: pipeline
status: [failed]
branch: main
account: mate-ci
agent: ci-assistant
- on: note
mention: true
agent: reviewer
policies:
cooldown: 5m
concurrency:
group/repo: 3
default_timeout: 1h