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.
Authority resolution
Section titled “Authority resolution”The effective authority set for a job is computed as:
effective = agent.permissions − trigger.deny − tenant.denyExplicit 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.
Deny layers
Section titled “Deny layers”| 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.) |
Example
Section titled “Example”# tenant configdeny: - 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}The nine authorities
Section titled “The nine authorities”| 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).
approve_mr is opt-in
Section titled “approve_mr is opt-in”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.
Tools per authority
Section titled “Tools per authority”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.
Where the permissions are enforced
Section titled “Where the permissions are enforced”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.
Narrowing permissions in .mate.yml
Section titled “Narrowing permissions in .mate.yml”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.
agents: reviewer: permissions: [read, comment] # OK: subset of tenant reviewer's [read, comment, push_branch, open_mr]# .mate.yml — this will failagents: reviewer: permissions: [read, comment, merge] # Error: merge is not in the base agent's permissionsSetting up permissions in practice
Section titled “Setting up permissions in practice”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]