Skip to content

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.

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.

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.

An actor-bearing trigger takes the acting account from the webhook payload:

  • on: issue with assigned: true — the account newly added as assignee.
  • on: merge_request with assigned: true — the account newly added as assignee.
  • on: merge_request with review_requested: true — the account newly added as reviewer, or re-requested via GitLab’s “re-request review”. Mutually exclusive with assigned: true on the same trigger.
  • on: note with mention: true (the default) — the account whose @username appears 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-agent

Fires 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).

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

If 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-agent

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

- on: pipeline
status: [failed]
scope: [branch]
branch: main
account: mate-ci
agent: ci-assistant

Filters: 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.

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-security

When one webhook yields several candidates, Mate evaluates them in a fixed order of event kinds:

  1. push
  2. tag_push
  3. issue
  4. merge_request
  5. note
  6. pipeline
  7. job
  8. deployment
  9. release
  10. wiki_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.

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.concurrency can 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 with 503, which signals GitLab to retry.
  • policies.cooldown paces 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).

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

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.

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.
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:
assignee_in: [mate-junior, mate-senior] # issue / merge_request only

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

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 only

See Permissions for the full resolution model.

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

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