Accounts, Agents, Triggers
Mate’s configuration model has three building blocks: managed accounts, agents, and triggers. Understanding how they interact is the key to configuring Mate well.
Managed accounts
Section titled “Managed accounts”A managed account is a GitLab user whose Personal Access Token (PAT) you have registered with Mate in the console (Managed accounts). When an event fires, the account is the actor: it clones the repository, posts comments, and takes actions in GitLab under that user’s identity.
Use a dedicated GitLab user for this, not your personal one. The token needs the api scope. Mate derives the username by calling the GitLab API — you do not configure the username yourself. Accounts are registered in the console, never in YAML.
Accounts are intentionally minimal. They carry no behavior — only an identity and credentials. To change what an account does, you configure an agent and a trigger.
Agents
Section titled “Agents”An agent is a named configuration bundle that describes how a job should run:
- Which LLM backend (
claude-code,codex,omporopencode) - Which model (
model:field) - The system prompt
- The authority profile — which GitLab operations the job may perform
- Optional image, environment, clone-strategy (
variables:) and timeout overrides
Agents have arbitrary names. An agent only runs when a trigger explicitly names it. If a GitLab event matches no trigger, no job is dispatched.
Several agents let you describe specialized behavior (a strict code reviewer, a junior fixer, a security auditor) without creating additional GitLab users.
Triggers
Section titled “Triggers”A trigger binds a GitLab event to an agent. When the event fires, Mate evaluates every trigger against it, and every trigger whose predicates match fires — not just the first. See How many jobs does one event create? for the full model.
Each trigger specifies:
on:— the event type (issue,merge_request,note,pipeline, and others)agent:— which agent’s configuration drives the job- Event filters such as
assigned: true,review_requested: true,mention: true,status: [failed], orlabel:(a filter on issue and MR events, not a standalone trigger) - Optional
if:conditions — narrow the trigger to specific assignees, branches, labels, or MR properties - Optional
deny:— subtract specific authorities from the effective permission set for this trigger
Mate does not filter an account’s own actions: a job’s agent can assign itself, request its own review or @-mention itself, and each of those starts a new job. This is how an agent chains follow-up work, and it is also why cooldown and timeouts matter. Only one job runs at a time per issue or MR, whichever account it acts as.
See the triggers reference for the full list of event types and filters.
The two axes: actor and config
Section titled “The two axes: actor and config”The most important thing to internalize: the GitLab actor and the effective configuration are chosen independently.
| What | Chosen by | How |
|---|---|---|
| Actor — whose PAT acts, whose username appears in comments | The GitLab event | The account that was assigned, asked for review, or @-mentioned. For events with no account in the payload (pipelines, pushes, and so on), the trigger’s account: field. |
| Effective config — model, system prompt, permissions | The matched trigger | The trigger’s agent: field. If no trigger matches, no job is dispatched. |
A trigger lets you decouple persona from identity. For example: you assign mate-junior to an issue, but a trigger routes that assignment to the mate-senior agent’s configuration — mate-junior’s PAT acts, mate-senior’s model and prompt drive the behavior.
Config sources: workspace YAML and .mate.yml
Section titled “Config sources: workspace YAML and .mate.yml”Configuration lives in two places that share the same schema:
- Workspace YAML — edited in the console (Agents & triggers, with a visual editor and a YAML tab). Workspace-wide defaults. This layer is the hard ceiling for authorities.
.mate.ymlat the repository root — per-repo overrides, versioned with the code.
The two are merged on every webhook. Repo-level config may extend or narrow agents and add triggers but cannot escalate authorities beyond the workspace-level cap. See Tenant configuration for the full merge rules.
Worked example
Section titled “Worked example”This example uses two accounts and two agents across workspace and repo config.
Workspace config:
version: 1
agents: mate-senior: backend: claude-code model: anthropic/claude-sonnet-5.5 system_prompt: | You are a senior engineer. Think carefully before making changes. permissions: [read, comment, push_branch, open_mr]
mate-junior: backend: claude-code model: anthropic/claude-haiku-4-5 system_prompt: | You are a junior engineer. Implement the described task with the smallest reasonable change. permissions: [read, comment, push_branch, open_mr]
triggers: - on: merge_request assigned: true if: { assignee: mate-junior } agent: mate-senior # mate-junior assigned -> mate-senior's config runs
- on: issue assigned: true agent: mate-senior # any issue assignment -> mate-senior's config runs
policies: cooldown: 5m concurrency: group/repo: 2The two accounts mate-junior and mate-senior are registered in the console; their usernames come from GitLab.
Repo .mate.yml (for one specific repository):
version: 1
agents: code-reviewer: extends: mate-senior model: anthropic/claude-opus-4-7 system_prompt: | You are a strict code reviewer. Comment only on real issues. permissions: [read, comment]
triggers: - on: merge_request review_requested: true agent: code-reviewerWhat happens for each event:
| Event | Account involved | Actor | Effective agent | Permissions |
|---|---|---|---|---|
| MR assigned | mate-junior |
mate-junior |
mate-senior |
read, comment, push_branch, open_mr |
| MR assigned | mate-senior |
— | (no matching trigger) | no dispatch |
| Issue assigned | mate-senior |
mate-senior |
mate-senior |
read, comment, push_branch, open_mr |
| Review requested on an MR | mate-senior |
mate-senior |
code-reviewer |
read, comment |
Repo triggers are evaluated first (the repo list is placed ahead of the workspace list), and all matching triggers fire.
Authority vocabulary
Section titled “Authority vocabulary”The permissions: field on an agent lists which GitLab operations the job may perform. Explicit deny: at the trigger or workspace level subtracts from that set.
| Authority | What it allows |
|---|---|
read |
Read issues, MRs, files, pipelines, project metadata |
comment |
Post comments and discussion replies on issues and MRs |
push_branch |
Create and delete branches, push commits, resolve MR discussions |
open_mr |
Create and update merge requests |
merge |
Merge a merge request |
close_issue |
Close an issue |
update_issue |
Create and edit issues, link issues, change state |
touch_ci |
Create, retry or cancel pipelines; retry or cancel jobs |
approve_mr |
Approve a merge request (opt-in, see below) |
approve_mr (the approve_merge_request tool) is opt-in: off unless you list it in an agent’s permissions:. GitLab’s own approval rules (such as “prevent approval by author”) still apply. See Permissions for the full list.