Triggers

Triggers are the rules that decide when Mate spawns an agent job. Each trigger names one event type and one agent. The triggers: list is ordered — Mate evaluates entries top to bottom and the first matching trigger fires. Subsequent entries are skipped. Exactly one job is spawned per event.

Overview

triggers:
  - on: <event-type>            # required
    agent: <agent-name>         # required
    deny: [<authority>, ...]    # optional, subtract from agent's effective permissions
    if: { ... }                 # optional, additional AND-combined conditions
    when: { ... }               # optional, secondary filter (see Accepted but not yet enforced)
    # event-specific fields (see each event below)

Both the tenant config and .mate.yml may define triggers. When a repository has a .mate.yml, its triggers are prepended to the tenant list — repo triggers are always evaluated first.

The six event types

issue_assigned

Fires when a registered Mate bot is newly added as an assignee on an issue.

- on: issue_assigned
  agent: my-agent

The acting bot is the one that was just assigned. If the bot was already an assignee and the issue is updated for another reason, this event does not fire.

mr_assigned

Fires when a registered Mate bot is newly added as an assignee on a merge request.

- on: mr_assigned
  agent: my-agent

Same semantics as issue_assigned: fires only on the transition from not-assigned to assigned.

comment_mention

Fires when a comment is posted containing @<bot-username> at a word boundary. The match is case-sensitive and must be an exact username match.

- on: comment_mention
  agent: my-agent

This event fires for comments on both issues and merge requests. The acting bot is the one whose username was mentioned.

Optional field: mention

Restrict the trigger to a specific bot username. Useful when multiple bots are registered and you want different triggers for each.

- on: comment_mention
  mention: mate-reviewer
  agent: reviewer

label_applied

Fires when a label is newly applied to an issue or MR whose assignees include a registered Mate bot.

- on: label_applied
  label: "agent/review"    # required glob pattern
  agent: my-agent

The label: field is required for this event. Its value is a shell-glob pattern matched against the label name. If the issue or MR has no Mate bot in its assignees, no trigger runs — a label alone is not enough.

mr_opened

Fires when a merge request is opened, reopened, or transitions from draft to ready. The acting bot must be in the MR’s assignees.

- on: mr_opened
  agent: my-agent

Optional fields:

Field	Type	Description
target_branch	glob	Fire only when the MR targets this branch pattern.
draft	bool	When true, fire only for draft MRs. When false, fire only for non-draft (ready) MRs. When absent, fire for both.

- on: mr_opened
  target_branch: main
  draft: false
  agent: my-agent

pipeline_failed

Fires when a pipeline finishes with a failed status on a branch that has an open MR. Mate resolves the open MR by source branch; no bot-assignee check is performed.

- on: pipeline_failed
  agent: my-agent

Optional field: branch_pattern

Fire only for pipelines on branches matching this glob.

- on: pipeline_failed
  branch_pattern: "feat/*"
  agent: ci-assistant

Evaluation order

When a webhook arrives, Mate evaluates triggers in this fixed order across event kinds:

1. mr_opened
2. mr_assigned
3. issue_assigned
4. label_applied
5. comment_mention
6. pipeline_failed

Within each event kind, triggers are evaluated in YAML order (repo triggers before tenant triggers). The first match across both the kind ordering and the YAML ordering wins. If no trigger matches, no job is spawned.

Note

A single webhook from GitLab can carry signals for more than one event kind. The evaluation order above ensures deterministic behavior when multiple triggers could theoretically fire from the same webhook.

if: conditions

The if: block specifies additional conditions that must all be true for the trigger to match. All conditions in one if: block are AND-ed together. For OR semantics, write two separate trigger entries.

- on: mr_opened
  agent: reviewer
  if:
    target_branch: main
    mr_draft: false

Identity matchers

These perform exact string comparisons.

Key	Description
assignee	The GitLab username of the bot currently assigned to the issue or MR.
mentioned_user	The GitLab username that was mentioned (for comment_mention events).
author	The GitLab username of the issue, MR, or comment author.

Pattern matchers

These use shell-style glob patterns (Go path.Match semantics: * matches any sequence of characters within a single path segment and does not cross /; ** is not supported and behaves like *, not as a recursive glob).

Key	Type	Description
branch_pattern	glob	Source branch name of the MR or pipeline.
target_branch	glob	Target branch name of the MR.
label	glob	At least one label on the issue or MR matches this pattern.
labels	list of globs	At least one label matches any pattern in the list.

State matchers

Key	Type	Description
mr_state	string	MR state: opened, merged, or closed.
mr_draft	bool	true requires the MR to be a draft; false requires it to be ready.

Combining conditions

All conditions in one if: block must be satisfied for the trigger to fire. To express OR, write multiple triggers:

# OR: fire for either of two target branches
- on: mr_opened
  agent: reviewer
  if:
    target_branch: main

- on: mr_opened
  agent: reviewer
  if:
    target_branch: release/*

when: filter

The when: block is accepted for schema compatibility but currently has no enforced keys. See Accepted but not yet enforced below.

Unknown keys inside when: are a validation error.

deny: on triggers

The deny: field subtracts one or more authorities from the agent’s effective permission set for this specific trigger. It does not affect the agent when reached by other triggers.

- on: pipeline_failed
  agent: contributor
  deny: [push_branch, open_mr]   # comment only for this trigger

See Permissions for the full resolution model.

Concurrency and cooldown

Two policies control how many jobs a trigger can cause:

• policies.concurrency — maximum simultaneous jobs for the tenant. When the cap is reached, new matching events are queued.
• policies.cooldown — minimum time between a job reaching a terminal state and a new job being enqueued on the same repository. A trigger that would fire within this window is silently suppressed.

Both are set in the policies: block.

Accepted but not yet enforced

The following fields are accepted by YAML validation but currently have no effect at match time. Do not rely on them to filter which triggers fire.

Caution

when: assignee_in — parsed and schema-valid, but never evaluated. A trigger with assignee_in fires regardless of which bot was assigned. To route by assigned bot, use if: assignee instead (exact-match string comparison, enforced):

# Working alternative: route by which bot was assigned
- on: issue_assigned
  agent: junior
  if:
    assignee: mate-junior

- on: issue_assigned
  agent: senior
  if:
    assignee: mate-senior

Caution

if: author_role — the matching context never carries a role value. A trigger that sets author_role will never fire. Remove this condition from any trigger until it is implemented.

Caution

if: mr_size_max — the diff size is never populated in the matching context. This condition always passes (it has no filtering effect). Do not depend on it to gate large MRs.

Caution

if: path_pattern — file paths are never populated in the matching context. A trigger that sets path_pattern will never fire. Remove this condition from any trigger until it is implemented.

Complete example

triggers:
  # label-routed: different agents for review vs. implementation
  - on: label_applied
    label: "agent/review"
    agent: reviewer

  - on: label_applied
    label: "agent/fix"
    agent: fixer

  # route by which bot was assigned (if: assignee is enforced)
  - on: issue_assigned
    agent: junior
    if:
      assignee: mate-junior

  - on: issue_assigned
    agent: senior
    if:
      assignee: mate-senior

  # review only non-draft MRs targeting main
  - on: mr_opened
    agent: security-reviewer
    if:
      target_branch: main
      mr_draft: false

  # pipeline failures: comment only, no code push
  - on: pipeline_failed
    agent: ci-assistant
    deny: [push_branch, open_mr]

  # mention fallback: catch-all for any bot mention
  - on: comment_mention
    agent: reviewer