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).
Top-level structure
Section titled “Top-level structure”version: 1 # optional; if present, must be 1allowed_users: [<username>, ...] # optional, who may trigger Matedeny: [<authority>, ...] # optional, tenant-wide blanket denyagents: { ... } # map of agent-name → definitiontriggers: [ ... ] # list; every matching trigger fires (see Triggers reference)policies: { ... } # optionalUnknown top-level keys are a validation error. Managed accounts are registered in the console (Managed accounts), not in this YAML.
allowed_users
Section titled “allowed_users”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 - mergeUnknown authority strings in deny: are a validation error.
Agents
Section titled “Agents”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: 30mAgent fields
Section titled “Agent fields”| 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
Section titled “backend”| 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.5anthropic/claude-sonnet-5.5anthropic/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.
permissions
Section titled “permissions”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]Inheritance
Section titled “Inheritance”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 unchangedInheritance cycles (A extends B extends A) are rejected at validation time.
Environment variables
Section titled “Environment variables”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 resources
Section titled “Container resources”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.
Triggers
Section titled “Triggers”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: falsePolicies
Section titled “Policies”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.
Complete example
Section titled “Complete example”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