Menu

Mattering Automations GitLab integration

Connect GitLab to Mattering Automations: issues, merge requests and approvals, branches, commits, CI pipelines and jobs, releases, labels, projects, and groups as workflow steps, authenticated with a GitLab access token. Works with GitLab.com and self-managed instances.

The Mattering Automations GitLab integration adds the GitLab REST API v4 to your automation canvas: list and search issues in a project or across a group, open, edit, comment on, and close them, work merge requests end to end from diffs and commits through approvals to the merge itself, create branches and commits, run and inspect CI pipelines and jobs including the raw job log, publish releases, manage labels, and read projects, groups, and members.

Two GitLab specifics are handled for you and worth knowing before you start. Self-managed and GitLab Dedicated instances are supported through an optional API base field on every node, so one workspace can automate GitLab.com and a private instance side by side. And a project, group, branch, or label can be named the way you already read it, because the connector URL-encodes path values rather than making you do it.

Setup takes a few minutes: create an access token in GitLab, attach it as a credential in Mattering, and run one read-only node to confirm it works. This guide walks through each step and ends with the full node reference.

Before you start

  • A GitLab account with access to the projects and groups you want to automate, on GitLab.com or on a self-managed instance you can reach over the network.
  • A Mattering workspace with access to the Automations app.
  • Permission to create an access token in GitLab. A personal access token carries your own permissions and nothing more, so your role in the project or group decides what the automations can do.
  • For a self-managed or GitLab Dedicated install, the base URL of your instance, for example https://gitlab.example.com.

Create a GitLab access token

Mattering authenticates to GitLab with a single access token, sent as the PRIVATE-TOKEN header that GitLab documents for personal, project, and group access tokens. The token is never placed in a URL. A personal access token is the usual choice; a project or group access token works the same way and narrows the blast radius to one project or group.

Sign in to GitLab and open User Settings from your avatar menu.
Go to Access Tokens and click Add new token.
Name the token so it says where it will be used, such as Mattering Automations, and set an expiry date.
Select the api scope. That is the practical choice: it covers reads and writes, which is what most automations need. Choose read_api instead if the workflow should never change anything in GitLab.
Click Create personal access token and copy the value.
GitLab shows the token once, at creation. If you leave the page without copying it, you cannot retrieve it later; create a new one and revoke the old.
To scope access to a single project or group instead of your whole account, create the token from that project's or group's own Settings, then Access Tokens page. The connector accepts it exactly the same way.

Connect GitLab to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose GitLab from the list.
Click Create new credential, paste your access token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Connect. All 82 GitLab nodes appear in your canvas palette.
This connector has no separate connection test button, because the host can be your own instance rather than GitLab.com. GitLab: Get Current User takes no parameters and is the auth probe: run it once and a successful response tells you the token and the host are both right.

Verify it works

After connecting, open any automation canvas and check the palette: a GitLab section should list the query and action nodes. Drop GitLab: Get Current User onto the canvas, leave the config empty, and run a test step. It is a safe read that takes no arguments, so a successful response returns the username, name, and id of the account the token belongs to and confirms the credential works.

If you are on a self-managed or GitLab Dedicated instance, set the API base field on that same node to your instance host, for example https://gitlab.example.com, and run it again. Blank means GitLab.com, so a self-managed token left on the default host will fail against an account that does not exist there. You can paste the host with or without https and with or without the /api/v4 suffix; the connector resolves all of those to the same API root.

Next, add GitLab: List Projects, set membership to true, and run it. The response gives you each project's numeric id and full path. Either of those is a valid project identifier for every other node, so copy one and keep it handy.

To confirm project-level access, add GitLab: List Project Issues with that project and run it. A successful response lists the project's issues, newest first, and means the token can read the surfaces your workflows will use.

Node reference

82 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 41

GitLab: Get Branch

gitlab_get_branch

Get a single branch, including its head commit.

GitLab: Get Commit

gitlab_get_commit

Get a single commit by SHA, branch name, or tag name.

GitLab: Get Commit Diff

gitlab_get_commit_diff

Get the file by file diff of a single commit.

GitLab: Get Current User

gitlab_get_current_user

Get the account the access token belongs to. Takes no parameters, so this is the connector's auth probe: run it first to confirm the token and the host are right.

GitLab: Get Group

gitlab_get_group

Get one group by numeric id or full path.

GitLab: Get Issue

gitlab_get_issue

Get one issue by its project internal id, with author, assignees, labels, milestone, and time tracking totals.

GitLab: Get Issue Comment

gitlab_get_issue_note

Get one comment on an issue by its note id.

GitLab: Get Job

gitlab_get_job

Get one CI job with its status, stage, timings, runner, and the commit it ran on.

GitLab: Get Job Log

gitlab_get_job_log

Get a job's log (trace) as plain text. GitLab returns raw text here rather than JSON, so the log arrives on the `log` field and the last 200 lines are also split out on `tail` for posting into a chat message.

GitLab: Get Latest Pipeline

gitlab_get_latest_pipeline

Get the most recent pipeline for a branch or tag. Without ref, the project's default branch is used.

GitLab: Get Latest Release

gitlab_get_latest_release

Get the project's latest release through GitLab's permalink, so you do not need to know the tag name.

GitLab: Get Merge Request

gitlab_get_merge_request

Get one merge request. Read detailed_merge_status to find out whether it can be merged and why not if it cannot.

GitLab: Get Merge Request Approvals

gitlab_get_merge_request_approvals

Get the approval state of a merge request: how many approvals are required, how many are left, and who has approved. Available on all tiers.

GitLab: Get Merge Request Comment

gitlab_get_merge_request_note

Get one comment on a merge request by its note id.

GitLab: Get Pipeline

gitlab_get_pipeline

Get one pipeline with its status, duration, triggering user, and detailed status block.

GitLab: Get Pipeline Variables

gitlab_get_pipeline_variables

List the variables a pipeline was started with. Treat the values as sensitive: they can carry secrets passed at trigger time.

GitLab: Get Project

gitlab_get_project

Get one project by numeric id or full path, including its default branch, visibility, URLs, and namespace.

GitLab: Get Release

gitlab_get_release

Get one release by its tag name, including its assets and notes.

GitLab: Get User

gitlab_get_user

Get a single user by numeric id.

GitLab: List Branches

gitlab_list_branches

List a project's repository branches with their protection status and head commit.

GitLab: List Commits

gitlab_list_commits

List repository commits. Filter by branch or tag, by date window, by file path, or by author.

GitLab: List Group Issues

gitlab_list_group_issues

List issues across every project in a group, including its subgroups. Same filters as the project issue list.

GitLab: List Group Members

gitlab_list_group_members

List the direct members of a group with their access levels.

GitLab: List Group Merge Requests

gitlab_list_group_merge_requests

List merge requests across every project in a group, including its subgroups. The review-queue view for a whole team.

GitLab: List Group Projects

gitlab_list_group_projects

List the projects in a group. Set include_subgroups to true to walk the whole subgroup tree.

GitLab: List Groups

gitlab_list_groups

List the groups visible to the token.

GitLab: List Issue Comments

gitlab_list_issue_notes

List the notes (comments) on an issue. GitLab returns both human comments and system notes, so filter on the `system` field when you only want what people wrote.

GitLab: List Issues Closed by a Merge Request

gitlab_list_merge_request_closing_issues

List the issues a merge request will close when it merges, taken from its closing pattern references.

GitLab: List Labels

gitlab_list_labels

List a project's labels, optionally with issue and merge request counts.

GitLab: List Merge Request Comments

gitlab_list_merge_request_notes

List the notes (comments) on a merge request. Both human comments and system notes come back, so filter on the `system` field for review conversation only.

GitLab: List Merge Request Commits

gitlab_list_merge_request_commits

List the commits that a merge request would bring in.

GitLab: List Merge Request Diffs

gitlab_list_merge_request_diffs

List the file diffs in a merge request, one entry per changed file. This is the supported replacement for the deprecated changes endpoint.

GitLab: List Merge Requests

gitlab_list_merge_requests

List the merge requests in a project. Filter by state, branch, author, assignee, reviewer, labels, or draft status.

GitLab: List Pipeline Jobs

gitlab_list_pipeline_jobs

List the jobs in one pipeline. The usual first step after a pipeline-failed trigger: find which job failed, then read its log.

GitLab: List Pipelines

gitlab_list_pipelines

List a project's CI pipelines. Filter by status, branch, source, or the user who triggered them.

GitLab: List Project Issues

gitlab_list_issues

List the issues in a project, newest first by default. Filter by state, labels, milestone, assignee, or a free text search.

GitLab: List Project Jobs

gitlab_list_project_jobs

List a project's CI jobs across all of its pipelines.

GitLab: List Project Members

gitlab_list_project_members

List the direct members of a project with their access levels. Use this to turn a name into the numeric user id that assignee fields expect.

GitLab: List Projects

gitlab_list_projects

List projects visible to the token. Set membership to true for just the projects the token's user belongs to, which is almost always what an automation wants.

GitLab: List Releases

gitlab_list_releases

List a project's releases, newest first by default.

GitLab: List Users

gitlab_list_users

List users visible to the token. Filter by username or a free text search to resolve a username into the numeric id that assignee and reviewer fields expect.

Action nodes 41

GitLab: Approve Merge Request

gitlab_approve_merge_request

Approve a merge request as the user the access token belongs to. Available on all tiers. Reverse it with GitLab: Revoke Merge Request Approval.

GitLab: Cancel Job

gitlab_cancel_job

Cancel a running or pending job. Retry it afterwards if you need to.

GitLab: Cancel Pipeline

gitlab_cancel_pipeline

Cancel a pipeline and its running jobs. Retry it afterwards with GitLab: Retry Pipeline.

GitLab: Close Issue

gitlab_close_issue

Close an issue. This is the edit-issue endpoint with state_event fixed to close, so nothing else about the issue changes. Reopen it with GitLab: Update Issue.

GitLab: Comment on Commit

gitlab_create_commit_comment

Add a comment to a commit. Supply path, line, and line_type together to anchor the comment to a specific line of the diff.

GitLab: Comment on Issue

gitlab_create_issue_note

Add a comment to an issue. The comment is attributed to the user the access token belongs to.

GitLab: Comment on Merge Request

gitlab_create_merge_request_note

Add a comment to a merge request. The comment is attributed to the user the access token belongs to.

GitLab: Create Branch

gitlab_create_branch

Create a branch from an existing branch, tag, or commit SHA.

GitLab: Create Commit

gitlab_create_commit

Create a commit that adds, updates, moves, or deletes several files in one call. Each entry in actions needs an action of create, update, move, delete, or chmod plus a file_path.

GitLab: Create Issue

gitlab_create_issue

Create an issue in a project. Only the title is required. Assignees are numeric user ids, which GitLab: List Project Members resolves.

GitLab: Create Label

gitlab_create_label

Create a project label. Both name and color are required, and color is a six digit hex value with a leading hash.

GitLab: Create Merge Request

gitlab_create_merge_request

Open a merge request. source_branch, target_branch, and title are required. Prefix the title with Draft: to open it as a draft.

GitLab: Create Project

gitlab_create_project

Create a project. Supply name, path, or both. Without namespace_id the project lands in the token user's personal namespace.

GitLab: Create Release

gitlab_create_release

Create a release. If the tag does not exist yet, supply ref and GitLab creates the tag from it first.

GitLab: Delete Branch

gitlab_delete_branch

Delete a branch. DESTRUCTIVE: commits reachable only from this branch become unreferenced. Protected branches are refused.

GitLab: Delete Issue

gitlab_delete_issue

Delete an issue. DESTRUCTIVE and irreversible: the issue and its comments are gone. Requires Owner or administrator rights. Close the issue instead unless you really mean to erase it.

GitLab: Delete Issue Comment

gitlab_delete_issue_note

Delete a comment from an issue. DESTRUCTIVE and irreversible: the comment text is not recoverable.

GitLab: Delete Label

gitlab_delete_label

Delete a project label. DESTRUCTIVE: the label is removed from every issue and merge request that carries it.

GitLab: Delete Merge Request

gitlab_delete_merge_request

Delete a merge request. DESTRUCTIVE and irreversible, and it needs Owner or administrator rights. Close the merge request with GitLab: Update Merge Request instead unless you mean to erase it.

GitLab: Delete Merge Request Comment

gitlab_delete_merge_request_note

Delete a comment from a merge request. DESTRUCTIVE and irreversible: the comment text is not recoverable.

GitLab: Delete Merged Branches

gitlab_delete_merged_branches

Delete every branch already merged into the default branch. DESTRUCTIVE and bulk: protected branches are kept, everything else merged is removed. The work runs in the background.

GitLab: Delete Pipeline

gitlab_delete_pipeline

Delete a pipeline. DESTRUCTIVE and irreversible: the pipeline, its jobs, its logs, and its artifacts are removed. Cancel it instead if you only want it to stop.

GitLab: Delete Project

gitlab_delete_project

Delete a project. DESTRUCTIVE: this removes the repository, its issues, and its merge requests. Depending on instance settings the project is either marked for delayed deletion or removed at once.

GitLab: Delete Release

gitlab_delete_release

Delete a release. DESTRUCTIVE: the release, its notes, and its asset links are removed. The underlying Git tag is kept.

GitLab: Erase Job

gitlab_erase_job

Erase a job's log and artifacts. DESTRUCTIVE and irreversible: the job record stays but its output is gone. Read the log first if you need it.

GitLab: Fork Project

gitlab_fork_project

Fork a project into a namespace the token's user can write to. Forking runs in the background, so the response can arrive before the repository has finished copying.

GitLab: Merge a Merge Request

gitlab_merge_merge_request

Merge a merge request into its target branch. Returns 405 when the merge request cannot be merged yet, so check detailed_merge_status first or set merge_when_pipeline_succeeds.

GitLab: Move Issue

gitlab_move_issue

Move an issue to another project. GitLab closes the original and creates a copy in the target project, keeping a link between them.

GitLab: Play Manual Job

gitlab_play_job

Start a manual job, the API equivalent of pressing play in the pipeline view. This is how an automation triggers a gated deploy.

GitLab: Rebase Merge Request

gitlab_rebase_merge_request

Rebase the merge request's source branch onto its target branch. The rebase runs in the background: the response only confirms it was queued.

GitLab: Retry Job

gitlab_retry_job

Retry a single failed or canceled job. Returns the new job.

GitLab: Retry Pipeline

gitlab_retry_pipeline

Retry the failed and canceled jobs in a pipeline.

GitLab: Revoke Merge Request Approval

gitlab_unapprove_merge_request

Withdraw the token user's own approval from a merge request. Available on all tiers.

GitLab: Run Pipeline

gitlab_create_pipeline

Start a new pipeline on a branch or tag. Note the singular /pipeline path: this is the one write endpoint in the pipelines family that does not use the plural form.

GitLab: Update Issue

gitlab_update_issue

Update an issue. Only the fields you supply change. Use state_event close or reopen to move the issue between states, and add_labels or remove_labels to edit labels without replacing the whole set.

GitLab: Update Issue Comment

gitlab_update_issue_note

Edit the text of an existing issue comment.

GitLab: Update Label

gitlab_update_label

Rename or recolour a project label, or change its description and priority.

GitLab: Update Merge Request

gitlab_update_merge_request

Update a merge request. Only the fields you supply change. Use state_event close or reopen to change its state.

GitLab: Update Merge Request Comment

gitlab_update_merge_request_note

Edit the text of an existing merge request comment.

GitLab: Update Project

gitlab_update_project

Update a project's settings. Only the fields you supply are changed. Use the body passthrough for any attribute not typed here.

GitLab: Update Release

gitlab_update_release

Update a release's title, notes, milestones, or release date. The tag itself cannot be changed here.

Using the integration

On the automation canvas

GitLab nodes chain with every other node: a failed pipeline can open an assigned task in Mattering Productivity, an AI step can read a merge request diff before a human does, and a release can be announced in a message in the same flow. GitLab: List Project Members and GitLab: List Users turn a name into the numeric user id that assignee and reviewer fields expect.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can triage issues, read diffs, post review comments, approve, and merge through the same nodes your workflows use.

Pointing nodes at a self-managed instance

Every node carries an optional API base field. Leave it blank for GitLab.com, or set it to your instance host to reach a self-managed or GitLab Dedicated install. The value is normalized for you: a missing scheme becomes https, a trailing slash is trimmed, and /api/v4 is appended when it is not already there. Because the host sits on the node and not on the credential, one workspace can automate GitLab.com and a private instance at the same time with two different tokens.

Naming projects, branches, issues, and merge requests

A project or group can be given as its numeric id or as its full path, such as my-group/my-project. The connector URL-encodes path values, so you paste what you read in the browser and a slash does not break the call, and a value you already encoded is detected and left alone. Issues and merge requests are addressed by their per-project internal id, the number you see in the interface as #14 or !133, not the global id in the response body. The one documented exception is GitLab: Move Issue, whose target project is a body field and takes a numeric id only.

Reading CI without opening the pipeline view

GitLab: List Pipelines filters by status and branch, GitLab: List Pipeline Jobs finds the job that failed, and GitLab: Get Job Log returns the trace as plain text with the last 200 lines split out on their own field, which is the part you actually want in a chat message. GitLab: Retry Job and GitLab: Play Manual Job act on the result, the second being how an automation releases a gated deploy.

Reaching parameters the typed fields do not name

Every node accepts extra query parameters that are merged into the request, and every write node accepts a free-form body object, so a documented GitLab filter or attribute that is not individually typed stays reachable without waiting on a connector update.

Handling the destructive nodes

Eleven nodes are marked destructive in the palette, including GitLab: Delete Project, GitLab: Delete Issue, GitLab: Delete Merge Request, GitLab: Delete Branch, GitLab: Delete Merged Branches, GitLab: Delete Pipeline, GitLab: Erase Job, GitLab: Delete Release, and GitLab: Delete Label. Prefer the reversible alternative where one exists, GitLab: Close Issue over deleting an issue and GitLab: Cancel Pipeline over deleting a pipeline, and keep the rest out of agent-triggered paths unless a human step approves the run.

Troubleshooting

Every node returns 401 Unauthorized
The token is not being accepted. The usual causes are a value that was truncated on paste, a token that has been revoked, or a token created without an API scope at all. Recreate it in GitLab under User Settings, then Access Tokens, with the api scope selected (or read_api for a read-only automation), update the credential on the connector, and re-run GitLab: Get Current User. On a self-managed instance, also check the API base field before blaming the token: a GitLab.com token sent to your own host, or the reverse, is rejected the same way.
Nodes worked for weeks and now every one returns 401
The access token expired. GitLab tokens carry an expiry date, and an instance can enforce a maximum lifetime, so a working connector goes dead on that date with no warning inside Mattering. Create a fresh token, update the credential, and set a calendar reminder a little before the new expiry. A project or group access token expires the same way.
Reads work but a write returns 403 Forbidden
Two different things produce this. Either the token was created with read_api rather than api, which permits reads only, or the account the token belongs to does not have a high enough role in that project or group for the action. Check the scope first, then confirm the role with GitLab: List Project Members. Deleting an issue or a merge request needs Owner or administrator rights specifically, which is deliberate on GitLab's side.
A self-managed instance is not being reached
Set the API base field on the node. It is blank by default, and blank means GitLab.com, so a node left at the default calls gitlab.com no matter whose token it is holding. Paste your instance host, for example https://gitlab.example.com; the scheme, a trailing slash, and the /api/v4 suffix are all handled for you. If your install serves the API from a subpath, paste the full base including /api/v4. Set the field on every node in the workflow, not only the first.
A project or group node returns 404 Not Found
Use the URL path from the browser address bar, such as my-group/my-project, or the numeric id, not the project's display name. The connector URL-encodes the slash for you, which is what a direct API call would need, so do not encode it yourself as well. Run GitLab: List Projects with membership set to true and copy the id or path_with_namespace straight from the response. A 404 on a project that definitely exists usually means the token cannot see it: GitLab returns 404 rather than 403 for private projects, so check the account's membership.
An issue or merge request returns 404 even though the number is correct
Issues and merge requests are addressed by their per-project internal id, not the global id. The internal id is the number shown in the interface, #14 for an issue and !133 for a merge request. The id field in a response body is the global one and will 404 in the path. Comments, pipelines, jobs, and labels use plain ids, so this only bites on the issue and merge request nodes.
Only the first handful of results comes back
GitLab paginates list endpoints and the nodes return one page per run. Set per_page (GitLab caps it at 100) and loop over page in the automation until a page comes back empty. There is no auto-paging node, and the response Link headers are not surfaced, so the loop is yours to build. The same applies to throttling: if GitLab returns a 429 the node reports it on its output rather than retrying by itself, so add a wait and a retry where a workflow pulls hard.
Merging a merge request returns 405
GitLab refuses the merge because the merge request is not in a mergeable state: a pipeline is still running, approvals are outstanding, it is still a draft, or the branch has conflicts. Read detailed_merge_status with GitLab: Get Merge Request first and branch on it, or set merge_when_pipeline_succeeds so GitLab merges once the build goes green instead of failing now.
Updating an issue wiped its labels
The labels field replaces the entire label set with what you send, so passing one label removes the rest. Use add_labels and remove_labels on GitLab: Update Issue or GitLab: Update Merge Request when you mean to change labels incrementally, and keep labels for the case where you really are setting the full list.

GitLab is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products