# 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 1. In the sidebar, open **Connections** and press **Add connection**. 2. Type `gitlab` and choose **GitLab**. 3. Choose **Sign in with GitLab**. 4. 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. 1. Create an app in GitLab’s developer settings ([GitLab’s guide](https://gitlab.com/-/user_settings/personal_access_tokens)). 2. In GoRunner, copy the **Redirect address to add in GitLab’s developer settings**, and add it to the app. 3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**. [Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers) **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](https://docs.gorunner.io/build/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](https://docs.gorunner.io/embed/customer-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](https://docs.gorunner.io/build/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. - [Issue](https://docs.gorunner.io/apps/gitlab#fields-f-issue): Create · Get · Edit · Create Comment · Lock - [Merge Request](https://docs.gorunner.io/apps/gitlab#fields-f-mergerequest): Create · Get · Get Many · Update · Merge · Create Comment · Get Changes - [Project](https://docs.gorunner.io/apps/gitlab#fields-f-repository): Get · Get Issues - [File](https://docs.gorunner.io/apps/gitlab#fields-f-file): Create · Edit · Get · List · Delete - [Branch](https://docs.gorunner.io/apps/gitlab#fields-f-branch): Create · Get Many - [Release](https://docs.gorunner.io/apps/gitlab#fields-f-release): Create · Get · Get Many · Update · Delete - [Pipeline](https://docs.gorunner.io/apps/gitlab#fields-f-pipeline): Run · Get · Get Many · Retry Failed Jobs · Cancel - [User](https://docs.gorunner.io/apps/gitlab#fields-f-user): Get Projects Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/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](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list). ## 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](https://docs.gorunner.io/api/apps/get-app) returns every field. It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions). ### 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. Source: https://docs.gorunner.io/apps/gitlab