Skip to content

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.

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.

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

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.

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.

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.

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