Skip to content

Permissions

Mate uses an IAM-style permission model. Every agent declares a set of authorities it is allowed to use. At dispatch time, Mate computes the effective authority set by applying any deny rules from the trigger and from the tenant-wide configuration. The effective set determines which GitLab tools the agent is offered and which are accepted when it calls them.

The effective authority set for a job is computed as:

effective = agent.permissions − trigger.deny − tenant.deny

Explicit deny at any layer always wins. If an authority is listed in trigger.deny or in the top-level tenant.deny, it is removed from the effective set regardless of what agent.permissions says. An empty effective set means no job is started for that trigger — an agent with no granted authorities cannot do anything meaningful.

Layer Where it is set Scope
agent.permissions Agent definition in tenant config or .mate.yml Defines the maximum possible set for this agent.
trigger.deny Individual trigger entry Subtracts authorities for this trigger only. The agent’s full permissions are still used when the agent is invoked from other triggers.
tenant.deny Top-level deny: list in tenant config Subtracts authorities from every agent, for every trigger, across the entire tenant. Cannot be overridden by .mate.yml. (The console editor currently does not accept this key; see Tenant configuration.)
# tenant config
deny:
- merge # no agent may merge, tenant-wide
agents:
contributor:
permissions: [read, comment, push_branch, open_mr, merge]
triggers:
- on: issue
assigned: true
agent: contributor
deny: [push_branch] # this trigger: no push
- on: merge_request
assigned: true
agent: contributor
# no trigger deny; effective = {read, comment, push_branch, open_mr}
# (merge was removed by tenant.deny)

For the issue-assignment trigger:

{read, comment, push_branch, open_mr, merge}
− {push_branch} # trigger.deny
− {merge} # tenant.deny
= {read, comment, open_mr}
Authority What it allows
read Read repository content, file trees, issues, MRs, pipelines, jobs and logs, and all other project data.
comment Post comments and discussion replies on issues and MRs.
push_branch Create and delete branches, push commits to any branch (new or existing), and resolve MR discussions.
open_mr Open a new merge request, or update an existing MR’s title, description, target branch, labels, assignees, reviewers or state.
merge Merge an open MR. GitLab’s own merge rules still apply — Mate cannot bypass required approvals or pipelines.
close_issue Close an issue. Closing is an issue update, so this authority exposes the update_issue tool.
update_issue Create issues, link issues, and update issue fields: title, description, labels, assignees, and state.
touch_ci Create, retry, or cancel pipelines, and retry or cancel individual jobs.
approve_mr Approve a merge request. Opt-in: never granted by default.

Any unknown authority string in permissions: or deny: is a validation error and causes the entire config to be rejected.

push_branch grants push access to any branch in the project — new or existing, including main — the same as a human GitLab Developer. There is no branch-scoped variant. To keep an agent from pushing to main directly, protect the branch in GitLab (Settings → Repository → Protected branches).

Mate never approves its own work unless you choose to. An agent can approve merge requests only when approve_mr is listed in its permissions:; no default or template includes it, and a deny: entry removes it. GitLab’s own approval rules still decide whether the approval counts, including “prevent approval by author” for an MR the agent opened itself. Configure those rules in GitLab.

The tool service registers 52 tools. Each is offered only when one of the effective authorities unlocks it.

Authority Tools
read list_projects, get_project, list_group_projects, list_issues, get_issue, list_issue_notes, search_issues, list_merge_requests, get_merge_request, list_mr_notes, list_issue_discussions, list_mr_discussions, list_mr_commits, list_mr_diffs, list_mr_pipelines, search_merge_requests, list_pipelines, get_pipeline, wait_pipeline_finish, wait_pipeline_change, list_pipeline_jobs, get_job, get_job_log, list_branches, get_branch, list_commits, get_commit, compare_refs, get_file_content, list_repository_tree, get_current_user, get_user
comment create_issue_note, create_mr_note, create_mr_discussion, reply_to_issue_discussion, reply_to_mr_discussion
push_branch create_branch, delete_branch, resolve_mr_discussion
open_mr create_merge_request, update_merge_request
update_issue update_issue, create_issue, create_issue_link
close_issue update_issue (closing is an update with a state change)
merge merge_merge_request
approve_mr approve_merge_request
touch_ci create_pipeline, retry_pipeline, cancel_pipeline, retry_job, cancel_job

wait_pipeline_finish and wait_pipeline_change block for up to 840 seconds per call, so a single tool call can run for many minutes. In free text the agent writes into comments, discussions, and issue and MR descriptions, every line starting with / gets a zero-width space, so GitLab quick actions (such as /merge or /assign) do nothing; only the authorities above can cause those effects. The text renders unchanged.

The agent never talks to GitLab directly. Every GitLab operation goes through Mate’s permission-gated tool service, which checks the job’s effective authorities on every call. The agent sees every tool; a call its authorities do not cover is refused with an explanation that the action is not part of its job and what to do instead, such as telling people in a comment that the work is ready. The tool service also pins each job to the project that triggered it: calls naming another project are refused, and tools that cannot be confined to one project (such as list_group_projects) are denied.

The tool service acts with the managed account’s own token, so the account’s real GitLab membership is a second ceiling: the agent can never do more than that account could do itself in GitLab. Give the account the lowest GitLab role that fits the authorities you grant, and keep it out of projects Mate should not touch.

The managed account’s token never enters the agent container. The container holds the signed job credential, a short-lived read-only clone token (used for the initial git clone, then zeroed), and, when push_branch is granted, a per-job scoped push token so the agent can git push. Both are revoked when the job ends. See Security.

A per-repository .mate.yml can narrow an agent’s permissions but never expand them. The effective permissions of any repo-defined agent must be a subset of the base (tenant) agent’s permissions. Attempting to add an authority the base agent does not have is a merge-time error.

.mate.yml
agents:
reviewer:
permissions: [read, comment] # OK: subset of tenant reviewer's [read, comment, push_branch, open_mr]
# .mate.yml — this will fail
agents:
reviewer:
permissions: [read, comment, merge] # Error: merge is not in the base agent's permissions

Start with the minimum authority set your agent needs and expand only when required.

For a read-only reviewer that posts comments:

permissions: [read, comment]

For an agent that implements issues by pushing a branch and opening an MR:

permissions: [read, comment, push_branch, open_mr]

For an agent that fixes CI failures on the MR branch it is assigned to:

permissions: [read, comment, push_branch, touch_ci]

For an agent that manages issues (comments, updates labels, closes when done):

permissions: [read, comment, close_issue, update_issue]