Create your first agent

Mate’s behaviour is defined in a YAML config file 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).

You can edit this config during onboarding (Step 3) or at any time from the Config page in the tenant sidebar.

The config editor

The editor is a full-screen YAML editor with live validation. Errors are underlined inline and counted in the toolbar. The config is only saved when you click Save (or press Ctrl+S / Cmd+S). Navigating away with unsaved changes prompts you to confirm.

Minimal working example

The template the wizard starts with is a good base. Here is the simplest possible config that does something useful:

version: 1

agents:
  assistant:
    backend: claude-code
    model: "anthropic/claude-sonnet-4-6"
    system_prompt: |
      You are a helpful engineering assistant.
      Be concise. Do not make unrequested changes.
    permissions:
      - read
      - comment

triggers:
  - on: issue_assigned
    agent: assistant

This config defines one agent (assistant) that can read the GitLab project and post comments, and one trigger that starts that agent whenever an issue is assigned to the bot user.

Paste this into the editor (or keep the pre-loaded template), then click Save and continue.

Agents

Each entry under agents is a named configuration block:

Field	Required	Description
backend	yes	Use claude-code.
model	yes	Model identifier string. For OpenRouter: anthropic/claude-sonnet-4-6 or any model available on your account. For Anthropic direct: claude-sonnet-4-6.
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

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	Push commits to non-protected branches
push_mr_branch	Push commits to the source branch of an open MR
open_mr	Open new merge requests
merge	Merge an MR (subject to GitLab branch protection rules)
close_issue	Close issues
update_issue	Edit issue title, description, labels, state
touch_ci	Retry or cancel CI pipelines

Beta tool surface

During the closed beta the agent’s GitLab tool surface covers read and comment operations. The other authorities are accepted in configuration and control the scope of the job’s GitLab credential, but their write tools (branches, merge requests, issue updates, CI) are not yet enabled. Granting them today affects token scope only — it does not let the agent perform those actions yet.

Caution

read and comment are what works today — which is why the example starts there. Add broader permissions only when you have verified the agent’s behaviour on real issues.

Triggers

Each entry in the triggers list pairs an event with an agent. The first matching trigger wins.

Event	When it fires
issue_assigned	An issue is assigned to the bot user
mr_assigned	An MR is assigned to the bot user
mr_opened	An MR is opened (any author)
label_applied	A label matching the label: glob is added to an issue or MR
comment_mention	The bot is @-mentioned in a comment
pipeline_failed	A pipeline fails on a branch with an open MR

Example with multiple triggers:

triggers:
  - on: issue_assigned
    agent: assistant
  - on: comment_mention
    agent: assistant
  - on: label_applied
    label: "needs-review"
    agent: assistant

Saving and validating

Click Save or press Ctrl+S / Cmd+S. The editor validates the YAML schema server-side; any errors are shown inline with a count in the toolbar. The save button is disabled while there are errors.

Next: Run your first job