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.
Connect GitLab to Mattering
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
Nodes worked for weeks and now every one returns 401
Reads work but a write returns 403 Forbidden
A self-managed instance is not being reached
A project or group node returns 404 Not Found
An issue or merge request returns 404 even though the number is correct
Only the first handful of results comes back
Merging a merge request returns 405
Updating an issue wiped its labels
Related
The GitLab MCP
What connecting GitLab unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.