Skip to content

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.

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.

An agent is a named configuration bundle that describes how a job should run:

  • Which LLM backend (claude-code, codex, omp or opencode)
  • 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.

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], or label: (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 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.yml at 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.

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: 2

The 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-reviewer

What 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.

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.