GitLab
Open and update issues and merge requests, merge, commit files, create branches and releases, run CI/CD pipelines, and read projects on GitLab.com or your own GitLab.
Connect GitLab
- In the sidebar, open Connections and press Add connection.
- Type
gitlaband choose GitLab. - Choose Sign in with GitLab.
- Press Sign in with GitLab at the bottom of the sheet, then choose your account in GitLab’s window and allow access.
Or choose Paste your access token, paste it, and press Test and save. It stays until someone deletes it.
Sign in with GitLab (gitlab.com), or paste an access token: a personal access token (your avatar › Edit profile › Access tokens) or a project or group access token, with the api scope (read_api is enough for steps that only read). For a self-managed or Dedicated GitLab, enter its address and a token from it; the sign-in works for gitlab.com only.
What if it says “Sign-in isn’t set up here yet”?
Signing in with GitLab needs a GitLab app on this installation, and it has none yet. Until it is set up, Paste your access token works without it.
On Cloud: The sheet says “It’s set up once for everyone who uses this service, not by an organization.”
Self-hosted: An admin of the installation sees Set up GitLab sign-in instead, and sets it up once for everyone. Everyone else sees who to ask.
- Create an app in GitLab’s developer settings (GitLab’s guide).
- In GoRunner, copy the Redirect address to add in GitLab’s developer settings, and add it to the app.
- Paste the Client ID and Client secret, then press Save and sign in.
Can I use my own GitLab app?
Yes. In the sheet, open Use your own GitLab app and paste its Client ID and Client secret. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.
Connections says how to sign in again, rename or delete it. In a product that embeds GoRunner, Add connection can be missing: then your provider makes connections for you.
Start a workflow
Add a trigger and choose GitLab. The trigger uses the same connection as the steps.
On GitLab Event
Starts when GitLab sends one of the picked events for the project. Publishing the workflow adds a webhook to the project (with a secret token kept encrypted) and unpublishing removes it, so the connection's user needs the Maintainer role on the project and a token with the api scope. Every delivery is checked (its signature on GitLab 19 and later, its secret token before) and one that fails is refused; GitLab's retry or resend of the same delivery starts no second run.
- Owner · Optional
The user or group the project belongs to. Leave empty when the project is picked or written as its full path.
- Project · Required
The project to watch: pick it, or write its full path (group/project), id or link.
- Events · Required
Which events start the workflow. Any event subscribes to every kind listed.
Options: Any event to Project access token expiring (16 options).
- Push Branches · Optional
Only pushes to these branches (a wildcard like release/*). Empty: every branch.
A later step can use its data, such as {{trigger.commits}}, {{trigger.gitlab}}, {{trigger.object_attributes}} and 4 more. See Use data from earlier steps.
Do things in GitLab
Add a GitLab step, choose a Resource, then an Operation. Choose a row to see its fields.
- IssueCreate · Get · Edit · Create Comment · Lock
- Merge RequestCreate · Get · Get Many · Update · Merge · Create Comment · Get Changes
- ProjectGet · Get Issues
- FileCreate · Edit · Get · List · Delete
- BranchCreate · Get Many
- ReleaseCreate · Get · Get Many · Update · Delete
- PipelineRun · Get · Get Many · Retry Failed Jobs · Cancel
- UserGet Projects
Later steps read a step’s output by its name: see Use data from earlier steps.
Limits
- A reply from GitLab can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When GitLab says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.
Not in your list? See When an app isn’t here.
For developers
In the API, which calls apps pieces, GitLab is pieceId: "gitlab" with actionId: "gitlab", set by resource and an operation_… field, such as operation_branch. Its trigger is gitlabtrigger / gitlabtrigger. Get an app returns every field.
It can change something outside the run (writes_external). See How versions and side effects work.
GitLab › Issue
Create
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Title · Required
The issue's title.
- Description · Optional
In Markdown. Empty leaves it when editing.
- Labels · Optional
Label names. Editing replaces the issue's labels; a label that does not exist is created.
- Assignee IDs · Optional
GitLab user ids (numbers) to assign. Editing replaces the assignees.
- Milestone ID · Optional
The milestone's id. Empty leaves it.
- Due Date · Optional
YYYY-MM-DD. Empty leaves it.
- Confidential · Optional
Only project members with at least the Planner role see it.
Off by default.
Get and Lock
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Issue Number · Required
The issue's number in the project (7, #7) or its link.
Edit
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Issue Number · Required
The issue's number in the project (7, #7) or its link.
- Title · Optional
A new title. Empty leaves it.
- Description · Optional
In Markdown. Empty leaves it when editing.
- Labels · Optional
Label names. Editing replaces the issue's labels; a label that does not exist is created.
- Assignee IDs · Optional
GitLab user ids (numbers) to assign. Editing replaces the assignees.
- Milestone ID · Optional
The milestone's id. Empty leaves it.
- Due Date · Optional
YYYY-MM-DD. Empty leaves it.
- State · Optional
Close or reopen the issue.
Options: Leave as it is, Close, Reopen.
Default: Leave as it is.
Create Comment
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Issue Number · Required
The issue's number in the project (7, #7) or its link.
- Comment · Required
The comment, in Markdown.
- Internal Note · Optional
Visible only to project members with at least the Reporter role.
Off by default.
GitLab › Merge Request
Create
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Squash Commits · Optional
Squash the commits into one.
Off by default.
- Title · Required
The merge request's title. Start it with Draft: to open it as a draft.
- Source Branch · Required
The branch with the changes.
- Target Branch · Required
The branch the changes go into, such as main.
- Description · Optional
In Markdown. Empty leaves it when updating.
- Labels · Optional
Label names. Updating replaces the labels.
- Assignee IDs · Optional
GitLab user ids (numbers). Updating replaces them.
- Reviewer IDs · Optional
GitLab user ids (numbers) to ask for a review. Updating replaces them.
- Milestone ID · Optional
The milestone's id. Empty leaves it.
- Delete Source Branch · Optional
Delete the source branch once it is merged.
Off by default.
Get
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Merge Request Number · Required
The merge request's number in the project (12, !12) or its link.
Get Many
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- State · Optional
Options: Open, Closed, Merged, Locked, All.
Default: Open.
- Search · Optional
Text in the title or description.
- Labels · Optional
Only merge requests with all of these labels.
- Author · Optional
Only merge requests opened by this username.
- Target Branch · Optional
Only merge requests into this branch.
- Sort By · Optional
Options: Created, Updated, Merged.
Default: Created.
- Direction · Optional
Options: Newest first, Oldest first.
Default: Newest first.
- Return All · Optional
Read every item, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many items to return (1–1000).
Default: 50.
Shows when Return All is off.
Update
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Merge Request Number · Required
The merge request's number in the project (12, !12) or its link.
- Title · Optional
A new title. Empty leaves it.
- Target Branch · Optional
Another target branch. Empty leaves it.
- Description · Optional
In Markdown. Empty leaves it when updating.
- Labels · Optional
Label names. Updating replaces the labels.
- Assignee IDs · Optional
GitLab user ids (numbers). Updating replaces them.
- Reviewer IDs · Optional
GitLab user ids (numbers) to ask for a review. Updating replaces them.
- Milestone ID · Optional
The milestone's id. Empty leaves it.
- State · Optional
Close or reopen the merge request.
Options: Leave as it is, Close, Reopen.
Default: Leave as it is.
Merge
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Merge Request Number · Required
The merge request's number in the project (12, !12) or its link.
- Squash Commits · Optional
Squash the commits into one.
Off by default.
- Merge Commit Message · Optional
Empty uses GitLab's.
- Squash Commit Message · Optional
Empty uses GitLab's.
- Delete Source Branch · Optional
Delete the source branch after merging.
Off by default.
- When Checks Pass · Optional
Merge once the pipeline and other checks pass, instead of now.
Off by default.
- Head Commit · Optional
Merge only if the source branch is still at this commit SHA.
Create Comment
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Merge Request Number · Required
The merge request's number in the project (12, !12) or its link.
- Comment · Required
The comment, in Markdown.
Get Changes
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Merge Request Number · Required
The merge request's number in the project (12, !12) or its link.
- Return All · Optional
Read every item, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many items to return (1–1000).
Default: 50.
Shows when Return All is off.
GitLab › Project
Get
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
Get Issues
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- State · Optional
Options: Open, Closed, All.
Default: Open.
- Labels · Optional
Only issues with all of these labels.
- Search · Optional
Text in the title or description.
- Assignee · Optional
Only issues assigned to this username.
- Author · Optional
Only issues opened by this username.
- Updated Since · Optional
Only issues updated at or after this time (ISO 8601, such as 2026-11-01T00:00:00Z).
- Sort By · Optional
Options: Created, Updated, Due date, Priority.
Default: Created.
- Direction · Optional
Options: Newest or highest first, Oldest or lowest first.
Default: Newest or highest first.
- Return All · Optional
Read every issue, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many issues to return (1–1000).
Default: 50.
Shows when Return All is off.
GitLab › File
Create and Edit
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- File Path · Required
The file's path in the repository, such as docs/notes.md.
- From a File · Optional
Commit a file from an upload or an earlier step instead of text.
Off by default.
- File · Optional
Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). At most 10 MB.
Shows when From a File is on.
- File Content · Optional
The file's text.
Shows when From a File is off.
- Commit Message · Required
The commit's message.
- Branch · Optional
The branch to commit to. Empty uses the project's default branch.
- Author Name · Optional
Commit as this author (with Author Email). Empty commits as the connection's user.
- Author Email · Optional
The author's email address.
Get
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- File Path · Required
The file's path in the repository, such as docs/notes.md.
- Reference · Optional
A branch, tag or commit SHA to read from. Empty reads the default branch.
- Output as File · Optional
Return the content as a file (for images, archives and other binary files) instead of text.
Off by default.
List
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Folder Path · Optional
The folder to list, such as docs. Empty lists the top of the repository.
- Reference · Optional
A branch, tag or commit SHA to read from. Empty reads the default branch.
- Include Subfolders · Optional
List everything below the folder, not only its own entries.
Off by default.
- Return All · Optional
Read every entry, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many entrys to return (1–1000).
Default: 100.
Shows when Return All is off.
Delete
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- File Path · Required
The file's path in the repository, such as docs/notes.md.
- Commit Message · Required
The commit's message.
- Branch · Optional
The branch to commit to. Empty uses the project's default branch.
- Author Name · Optional
Commit as this author (with Author Email). Empty commits as the connection's user.
- Author Email · Optional
The author's email address.
GitLab › Branch
Create
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Branch Name · Required
The new branch's name, such as fix/login-timeout.
- From · Optional
The branch, tag or commit SHA it starts at. Empty starts at the default branch.
Get Many
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Search · Optional
Only branches whose name holds this text (^ for starts with, $ for ends with).
- Return All · Optional
Read every branch, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many branchs to return (1–1000).
Default: 50.
Shows when Return All is off.
GitLab › Release
Create
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Tag · Required
The release's tag, such as v1.4.0.
- Name · Optional
The release's title. Empty uses the tag.
- Notes · Optional
What changed, in Markdown.
- From · Optional
The branch or commit SHA a new tag is made from (needed when the tag does not exist yet).
- Released At · Optional
When it was or will be released (ISO 8601). Empty is now.
- Milestones · Optional
Milestone titles to attach.
Get and Delete
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Tag · Required
The release's tag.
Get Many
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Return All · Optional
Read every release, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many releases to return (1–1000).
Default: 50.
Shows when Return All is off.
Update
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Tag · Required
The release's tag.
- Name · Optional
The release's title. Empty uses the tag.
- Notes · Optional
What changed, in Markdown.
- Released At · Optional
When it was or will be released (ISO 8601). Empty is now.
- Milestones · Optional
Milestone titles to attach.
GitLab › Pipeline
Run
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Branch or Tag · Optional
The branch or tag to run the pipeline on. Empty uses the default branch.
- Variables · Optional
CI/CD variables for this pipeline by name, such as {"DEPLOY_ENV": "staging"}.
Get, Retry Failed Jobs and Cancel
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Pipeline ID · Required
The pipeline's id (or its link).
Get Many
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Project · Required
The project: pick it, or write its name, full path (group/project), id or link.
- Status · Optional
Options: Any, Created, Pending, Running, Succeeded, Failed, Canceled, Skipped, Manual, Scheduled.
Default: Any.
- Branch or Tag · Optional
Only pipelines on this branch or tag.
- Return All · Optional
Read every pipeline, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many pipelines to return (1–1000).
Default: 20.
Shows when Return All is off.
GitLab › User
Get Projects
- Owner · Optional
The user or group the project belongs to (a subgroup as group/subgroup); leave empty when the project is picked or written as its full path. For User, the user to read.
- Return All · Optional
Read every project, page by page (at most 1000; past that the step fails rather than stop early).
Off by default.
- Limit · Optional
How many projects to return (1–1000).
Default: 50.
Shows when Return All is off.