Triggers
Triggers are the rules that decide when Mate spawns an agent job. Each trigger names one event type (on:) and one agent. Every trigger whose predicates match a given event fires — see How many jobs does one event create? below for the full model.
Overview
Section titled “Overview”triggers: - on: <event-type> # required agent: <agent-name> # required account: <username> # managed account; see "Actor-bearing and actor-less triggers" deny: [<authority>, ...] # optional, subtract from the agent's permissions if: { ... } # optional, AND-combined conditions when: { assignee_in: [...] } # optional, issue / merge_request only # event-specific filters (see each event below)Both the workspace config and .mate.yml may define triggers. When a repository has a .mate.yml, its triggers are placed ahead of the workspace triggers — repo triggers are always evaluated first.
Event types
Section titled “Event types”on: takes one of ten values. All of them need the matching GitLab webhook event enabled (see Register a webhook).
on: |
Fires when | Actor |
|---|---|---|
issue |
An issue event arrives | The newly assigned account when assigned: true; otherwise account: |
merge_request |
A merge request event arrives | The newly assigned account (assigned: true) or newly requested reviewer (review_requested: true); otherwise account: |
note |
A comment is posted | The @-mentioned account (mention: true, the default); with mention: false, account: |
pipeline |
A pipeline changes status | account: |
push |
A branch is pushed | account: |
tag_push |
A tag is pushed | account: |
job |
A CI job changes status | account: |
deployment |
A deployment changes status | account: |
release |
A release is created, updated or deleted | account: |
wiki_page |
A wiki page is created, updated or deleted | account: |
The older fixed event names (issue_assigned, mr_assigned, mr_opened, comment_mention, label_applied, pipeline_failed) no longer exist. A config that still uses them fails to load.
Actor-bearing and actor-less triggers
Section titled “Actor-bearing and actor-less triggers”An actor-bearing trigger takes the acting account from the webhook payload:
on: issuewithassigned: true— the account newly added as assignee.on: merge_requestwithassigned: true— the account newly added as assignee.on: merge_requestwithreview_requested: true— the account newly added as reviewer, or re-requested via GitLab’s “re-request review”. Mutually exclusive withassigned: trueon the same trigger.on: notewithmention: true(the default) — the account whose@usernameappears in the comment, matched at a word boundary.
For these, account: is optional. When set, it is a filter: the trigger fires only if the payload’s actor is that account. It never substitutes the actor.
An actor-less trigger has no account in the payload (every other event, plus issue / merge_request without the actor-bearing flags, and note with mention: false). For these, account: names the actor and is required — unless the workspace has exactly one managed account, in which case it is implied. If the named account is not registered, the trigger is skipped.
Mate does not filter an account’s own actions: an account assigning itself, requesting its own review or @-mentioning itself starts a job like anyone else’s action would. This is how an agent can queue follow-up work for itself.
- on: issue assigned: true agent: my-agentFires once per newly added account assignee. If the account was already an assignee and the issue is updated for another reason, it does not fire again.
Filters: assigned (bool), action (list: open, close, update, reopen), label (glob; compared with the first label GitLab lists in the webhook payload).
merge_request
Section titled “merge_request”- on: merge_request assigned: true agent: my-agent
- on: merge_request review_requested: true agent: my-agent deny: [push_branch, open_mr, update_issue]Filters: assigned, review_requested (bool), action (list: open, reopen, update, approved, unapproved, merge, close), label (glob; first label in the payload), target_branch (glob), draft (bool). Un-drafting an MR also yields an event with draft: false.
Without assigned: or review_requested: the trigger is actor-less and needs account:. For example, reacting to every opened non-draft MR:
- on: merge_request action: [open, reopen] draft: false account: mate-reviewer agent: reviewerIf a registered account is removed as assignee (or, for review jobs, as reviewer), its live jobs on that issue or MR are stopped.
- on: note mention: true agent: my-agentFires on comments containing @<username> of a registered account, once per mentioned account. Mentions inside code (fenced or indented blocks, inline code spans) are ignored. Filters: mention (bool), noteable (list), action (list: create, update). Only comments on issues and merge requests ever produce events: commit and snippet are accepted values for noteable, but comments on commits and snippets never fire a trigger.
pipeline
Section titled “pipeline”- on: pipeline status: [failed] scope: [branch] branch: main account: mate-ci agent: ci-assistantFilters: status (list: failed, success, running, canceled, skipped, manual), branch (glob on the pipeline ref), and scope (list: branch, merge_request; omit for both). A pipeline counts as merge_request when the webhook carries a merge request, or when exactly one open MR has the pipeline’s branch as its source branch; otherwise as branch. Tag pipelines have neither scope, so a scope: filter never matches them.
Pipeline events fire on every status change, so always set status:. Because of that re-scoping, a scope: [branch] trigger does not fire for a branch that currently has a single open MR; use scope: [merge_request] or omit scope: to catch both. The matched MR is attached as context. A failure on a branch with no open MR (or with several) still fires as branch.
push, tag_push, job, deployment, release, wiki_page
Section titled “push, tag_push, job, deployment, release, wiki_page”These are actor-less and need account: (unless the workspace has one account).
on: |
Filters |
|---|---|
push |
branch (glob) |
tag_push |
tag (glob) |
job |
status (failed, success, running, canceled, manual), name (glob), stage (glob) |
deployment |
status (created, running, success, failed, canceled), environment (glob) |
release |
action (create, update, delete) |
wiki_page |
action (create, update, delete) |
push and job events are very frequent. Scope them tightly and set policies.cooldown.
Labels
Section titled “Labels”There is no standalone label trigger. label: is a filter on issue and merge_request triggers. Because a label trigger has no account in the payload unless you also use assigned: true, it normally needs account::
- on: merge_request action: [update, open] label: "agent/review" account: mate-security agent: mate-securityEvaluation order
Section titled “Evaluation order”When one webhook yields several candidates, Mate evaluates them in a fixed order of event kinds:
pushtag_pushissuemerge_requestnotepipelinejobdeploymentreleasewiki_page
Within each kind, triggers are evaluated in YAML order (repo triggers before workspace triggers). The order only determines the sequence in which triggers are checked, not how many fire. If no trigger matches, no job is spawned. Hosted workspaces without an active subscription get a note on the issue or MR instead of a job.
How many jobs does one event create?
Section titled “How many jobs does one event create?”All matching triggers fire. Mate does not stop at the first match. Every trigger — repo and workspace — whose on:, filters and if: conditions all pass produces one queued job. A pipeline failure can start a fixer agent and a notifier agent at the same time.
Identical work collapses. Dedup identity includes the agent name, so two different agents reacting to the same event never collapse into one. A logically identical action (same event kind, agent, project and target) that is still queued is dropped as a duplicate. An identical event that arrives while the earlier job is already running is not a duplicate: it queues a fresh job. Redelivered webhooks do not create duplicate jobs.
One active job per issue or MR. Jobs on the same issue or MR are serialized per project, across all agents and accounts: while one is starting or running, later events queue behind it. A still-queued job of the same kind, agent and account on that issue or MR is replaced by the newest event (it keeps its place in the queue); every mention gets its own job. Failed branch pipelines with no MR are serialized per branch the same way. Events with no issue or MR (such as push) are not serialized.
What bounds job count:
- Your plan’s mates bound how many jobs run at once across the workspace, and
policies.concurrencycan cap individual projects further; events beyond a cap queue. If the per-workspace queue itself fills up (1024 queued jobs) or the global queue does (1,048,576), Mate answers the webhook with503, which signals GitLab to retry. policies.cooldownpaces dispatch per repository; events queue and are dispatched as the window clears. They are not dropped.- Timeouts bound how long each job runs, see Limits.
There is no daily job cap and no limit on how deep a chain of agent-created work can go: a job’s own actions (assigning, mentioning, opening MRs) can trigger further jobs. The bounds above are the only brakes.
Every accepted event produces a single status note on the issue or MR, edited in place as the job moves through queued, working and done (or failed, canceled, or stopped because it was reassigned).
if: conditions
Section titled “if: conditions”The if: block specifies conditions that must all be true for the trigger to match. All conditions in one if: block are AND-ed. For OR semantics, write two separate triggers.
- on: merge_request review_requested: true agent: reviewer if: target_branch: main mr_draft: falseIdentity matchers
Section titled “Identity matchers”Exact string comparisons.
| Key | Description |
|---|---|
assignee |
The username of the account assigned. |
mentioned_user |
The username that was mentioned (for note events). |
author |
The username of the issue, MR, or comment author. |
Pattern matchers
Section titled “Pattern matchers”Shell-style glob patterns (Go path.Match semantics: * matches within a single path segment and does not cross /; ** is not supported).
| Key | Type | Description |
|---|---|---|
branch_pattern |
glob | Source branch of the MR, or of the MR the pipeline belongs to. Events with no associated MR (such as a branch pipeline with none open) never match. |
target_branch |
glob | Target branch name of the MR. |
label |
glob | The label matches (only the first label in the webhook payload is compared). |
labels |
list of globs | That label matches any pattern in the list. |
State matchers
Section titled “State matchers”| Key | Type | Description |
|---|---|---|
mr_state |
string | MR state: opened, merged, or closed. |
mr_draft |
bool | true requires a draft MR; false requires a ready one. |
Matchers such as author role, changed paths and MR size do not exist; a config that uses them is rejected.
when: filter
Section titled “when: filter”when: assignee_in: [mate-junior, mate-senior] # issue / merge_request onlyassignee_in is the one supported when: filter. The trigger fires only when one of the listed account usernames is the assignee: for actor-bearing triggers, the specific newly added account; for actor-less issue and MR triggers, anyone in the object’s current assignee list. Events that carry no assignee data (such as push or pipeline) never match a trigger with assignee_in. Unknown keys inside when: are a validation error.
assignee_in names should be registered managed accounts. Usernames are only known once Mate has resolved the accounts from GitLab, so the YAML is not rejected on save: ingest logs an error for an unknown name and that name simply never matches.
deny: on triggers
Section titled “deny: on triggers”The deny: field subtracts authorities from the agent’s permission set for this trigger only. It does not affect the agent when reached by other triggers.
- on: merge_request review_requested: true agent: mate deny: [push_branch, open_mr, update_issue] # review onlySee Permissions for the full resolution model.
Concurrency and cooldown
Section titled “Concurrency and cooldown”policies.concurrency— optional per-project caps on simultaneous jobs (group/repo: 2). When a project is at its cap, new matching events for it queue. Your plan capacity (number of mates) bounds the workspace total.policies.cooldown— minimum gap between job starts on the same repository, measured from the previous start. Events queue and dispatch as the window clears; with a cooldown set, a repository runs one job at a time.
Both are set in the policies: block of the workspace config.
Complete example
Section titled “Complete example”This is the shape of the “Teammate” template the console offers: one managed account, one agent, assignment, review, mention and failed-pipeline triggers.
triggers: - on: issue agent: mate assigned: true - on: merge_request agent: mate assigned: true - on: merge_request agent: mate review_requested: true deny: [push_branch, open_mr, update_issue] - on: note agent: mate mention: true - on: pipeline agent: mate status: [failed] scope: [branch] branch: main