Create your first agent
Mate’s behaviour is defined in a configuration that lives in the console. It specifies agents (what the LLM does and what permissions it has) and triggers (which GitLab events start an agent run).
This is the Create an agent and a trigger item on the workspace Home checklist. The button opens Agents & triggers in the sidebar, which you can use at any time.
Start from the Teammate template
Section titled “Start from the Teammate template”The console offers a Teammate template. It gives you one agent named mate and five triggers, so you can work with the managed account like a colleague:
- assign it an issue or merge request,
- request its review,
- @-mention it in a comment,
- and it reacts to failed pipelines on
main.
Click Use the Teammate template. The console fills in a backend and model that fit the kind of LLM key you saved (change them afterwards if you like):
| LLM key | Backend | Model |
|---|---|---|
| Anthropic direct | claude-code |
claude-sonnet-5-5 |
| OpenRouter | claude-code |
anthropic/claude-sonnet-5.5 |
| OpenAI-compatible | codex |
gpt-5.5 |
The template only fills the draft. Click Review & save, check the diff and confirm. The template’s agent is allowed read, comment, push_branch, open_mr and update_issue; its system prompt tells it to open Draft MRs, to never approve, and to never merge or push to the default or protected branches. (These are defaults in the prompt, not something Mate enforces; the permission list is what Mate enforces. Edit the prompt to change them.)
With exactly one managed account, the template names it on the triggers (account: <username>). With none or several, it leaves out the pipeline trigger, because a pipeline event names no acting account; add that trigger yourself with an account: once you know which account should handle failures.
You can edit agents and triggers with the visual editor or on the YAML tab; both work on the same draft. Changes are saved only when you save them, and the editor validates the schema and shows problems inline.
The configuration
Section titled “The configuration”With one managed account (mate-bot here), the template expands to roughly this:
version: 1
agents: mate: backend: claude-code model: <filled in for your key> permissions: [read, comment, push_branch, open_mr, update_issue] system_prompt: | You are a software engineer on this team. ...
triggers: - on: issue agent: mate account: mate-bot assigned: true - on: merge_request agent: mate account: mate-bot assigned: true - on: merge_request agent: mate account: mate-bot review_requested: true deny: [push_branch, open_mr, update_issue] - on: note agent: mate account: mate-bot mention: true - on: pipeline agent: mate status: [failed] scope: [branch] branch: mainAgents
Section titled “Agents”Each entry under agents is a named configuration block:
| Field | Required | Description |
|---|---|---|
backend |
yes | claude-code, codex, omp or opencode. It must be compatible with your LLM key; see Models and BYOK. |
model |
yes | Model identifier, written the way your provider names it. Mate does not validate it. |
system_prompt |
yes | The agent’s instructions. |
permissions |
yes | List of operations the agent may perform. See below. |
timeout |
no | Maximum wall-clock time per run, e.g. 30m. Defaults to a system limit if unset. |
Permissions
Section titled “Permissions”Start with the minimum set and expand as needed:
| Permission | What it allows |
|---|---|
read |
Read issue/MR content, project files, CI results |
comment |
Post comments on issues and MRs |
push_branch |
Create and delete branches, push commits (use GitLab protected branches to keep main safe) |
open_mr |
Open and update merge requests |
merge |
Merge an MR (GitLab’s merge rules still apply) |
close_issue |
Close issues |
update_issue |
Create and edit issues, link issues (also closes issues, like close_issue) |
touch_ci |
Create, retry or cancel pipelines and jobs |
approve_mr is opt-in and off by default: the agent cannot approve MRs unless you list it, and GitLab’s own approval rules still decide whether the approval counts. See Permissions.
Mates can continue their own work
Section titled “Mates can continue their own work”An agent with update_issue can create issues and link them. Assigning one to its own account, or @-mentioning its own account in a comment, starts a new job like any other event. This is allowed on purpose: the Teammate prompt uses it to split large work into child issues, or to queue a follow-up, and each one runs as its own job. Such jobs count against your mates (concurrent slots) like any other and queue when all are busy; the policies.cooldown setting still applies.
Triggers
Section titled “Triggers”Each entry in the triggers list pairs a GitLab event with an agent. Every entry whose event and conditions match fires — see How many jobs does one event create?.
| Trigger | When it fires |
|---|---|
on: issue with assigned: true |
An issue is assigned to the managed account |
on: merge_request with assigned: true |
An MR is assigned to the managed account |
on: merge_request with review_requested: true |
The managed account is asked to review an MR |
on: note with mention: true |
The account is @-mentioned in a comment |
on: pipeline with status: [failed] |
A pipeline fails (here: on branch main) |
on: also accepts push, tag_push, job, deployment, release and wiki_page; see Triggers.
Next: Run your first job