--- title: "GitLab" description: "Use gitlab.com and self-managed GitLab: issues, merge requests, to-dos, pipelines, releases and webhooks." canonical_url: "https://forges.link/providers/gitlab" --- # GitLab > Use gitlab.com and self-managed GitLab: issues, merge requests, to-dos, pipelines, releases and webhooks. The GitLab provider works with gitlab.com and self-managed GitLab. It can read and write issues, merge requests and commit comments, and it also covers to-dos, pipelines and jobs, commit statuses, releases, vulnerabilities and the webhooks of projects and groups. Merge requests have `kind: 'pull_request'`.

Detail	Value
Import	`forges/gitlab`
Factories	`gitlab()` , `gitlabLite()`
Auth	`token` , `anonymous`

## Authentication The provider accepts a personal, project, group or OAuth access token: ```ts import { gitlab } from 'forges/gitlab' const forge = gitlab({ auth: { type: 'token', token: process.env.GITLAB_TOKEN! }, }).create() ``` Project and group access tokens act as bot users, so they are the right choice when you need a credential that isn't tied to a person. If you leave out `auth`, the provider makes anonymous reads of public data. GitLab serves notes, labels, milestones, members, commit statuses, commit and code search and vulnerabilities only to signed-in users, even on public projects. An anonymous provider therefore reports comments and events, `repos.labels`, `repos.milestones`, `repos.collaborators`, `repos.permissionFor`, `checks.list`, `search.commits`, `search.code` and `securityAlerts` as unsupported. GitLab.com also shows full profiles only to signed-in users, so an anonymous `users.get()` returns the login, ID, name, avatar and URL, without `bio`, `createdAt` or follower counts. ## Self-managed instances To use a self-managed instance, set `baseUrl` to the root of the instance. The provider appends `/api/v4` itself: ```ts gitlab({ baseUrl: 'https://gitlab.example.com', auth }) ``` Webhook delivery logs and redelivery require GitLab 17.0 or later. If you know the version of the instance, pass it as `instanceVersion`. If you don't, `refreshCapabilities()` reads it from `/version`. ## Nested groups GitLab projects can live in nested groups, so `RepoRef.owner` holds the full namespace path. A project in a subgroup has `owner: 'acme/platform'` and `name: 'widgets'`. `repos.byOwner()` lists the projects of a group, or of a user when no group has that path. It leaves out projects that other groups share with the group, and it includes the projects of subgroups when you pass `subgroups: true`. GitLab doesn't record pushes, so `sort: 'pushed'` sorts by last activity, which also counts new issues and merge requests, and adds a `sort_unsupported` warning. ## Contributors GitLab counts commits per author email, so `repos.contributors()` returns one contributor per email, with a `name` and an `email` but no `actor`. ## Templates `repos.templates()` returns the description templates GitLab offers in the project, including those it inherits from its groups and the instance. The listing has names only, so each body costs one more request. A template has no `path`, since GitLab doesn't say which project it lives in. ## Notifications are to-dos On GitLab, `notifications.list()` reads the to-dos of the user. A to-do is either pending or done, and there is no separate read state, which affects how the notification operations behave: - `markRead()` rejects with `UnsupportedOperationError`, because there is nothing to mark as read. - `markDone()` marks the to-do as done. - `unsubscribe()` requires `{ thread }`, because GitLab can't look up a to-do by its ID. ## Event kinds from system notes GitLab reports changes to labels, states and assignments as English text in system notes, and the provider works out the kind of event by parsing that text. This is why `capabilities.eventKinds` is `'heuristic'`. When the provider doesn't recognise a note, the result is an event with `kind: 'other'`, and the `kindRaw` and `payload` of the event keep the original note. ## Approvals as reviews GitLab has approvals instead of reviews, so the provider presents them as reviews. `threads.reviews()` returns one review for each approver, with the ID `approval:`. `createReview({ event: 'approve' })` approves the merge request. `createReview({ event: 'comment', body })` opens a resolvable discussion on it instead, and the comment of the review it returns carries the discussion as its `thread`. For any other input, such as inline comments, it rejects with `UnsupportedOperationError`. `approve()` and `createReview({ event: 'approve' })` resolve with your approval, from the approvals in the response. When the merge request has more than one approver, the provider reads the signed-in account to tell which approval is yours, once per provider. Comments on a merge request are read by discussion, so a comment in a resolvable discussion has a `thread` whose ID `resolveReviewThread()` takes. `replyToReviewComment()` posts a note to that discussion, so pass it a comment that has a `thread`, such as one from `comments()`. A page holds whole discussions, so it can hold more comments than `perPage`. When the user isn't allowed to approve, GitLab responds with `401`. The provider raises this response as `InsufficientScopeError`. ## Merge request stats GitLab reports the number of changed files on a single merge request, but not the lines added or removed or the number of commits, so `thread.stats` holds only `changedFileCount`. Past the diff limit of the instance, GitLab reports a capped count such as `1000+` instead of the number, and `thread.stats` is absent. ## Releases GitLab releases have no draft or prerelease state, so every release is published as soon as you create it. `releases.create()` and `releases.update()` reject `draft: true` and `prerelease: true` with `UnsupportedOperationError` before they send a request. If the tag doesn't exist yet, `releases.create()` needs `target`, the branch or commit to tag. GitLab keys a release by its tag, so `releases.update()` can't change the tag or the commit of a release. It rejects a different `tag`, or any `target`, with `UnsupportedOperationError`. The assets of a GitLab release are links to arbitrary URLs and not files that GitLab hosts, so `releases.downloadAsset()` isn't available. To download an asset, fetch `asset.url` yourself. ## Committing files GitLab can't check the head of a branch as it commits, so with `expectedHead`, `contents.commitFiles()` reads the branch first and rejects with `BranchMovedError` when it has moved. A commit that lands between the two requests isn't caught. ## Search `search.commits()` uses GitLab's Advanced Search. GitLab doesn't report whether an instance has Advanced Search enabled, so the capability is `'experimental'`. On an instance without it, the search returns an empty page. Commit search accepts free text only. If you pass `author`, `committer`, `since`, `until` or `sort`, the result has a `filter_unsupported` warning. `search.threads()` has no `involves` filter, and it adds the same warning when you pass one. `search.code()` with a `repo` works on every GitLab tier. Pass `owner` instead to search a group, or neither to search the whole instance. Those two need Advanced Search or exact code search, so Premium or Ultimate. Without either, GitLab responds with `400`. GitLab.com has instance-wide code search switched off, so there it's a `403`. A personal namespace isn't a group, so an `owner` that names a user gets a `404`. A group or instance result names its project only by ID, so the provider looks up the projects of each page in one GraphQL request and remembers them. A project the token can't read leaves its results out of the page, with a `record_unreachable` warning. GitLab returns one result per excerpt, not per file, and without Advanced Search it lists a file again when its name matches as well as its contents. The provider merges the results for a file in a page into one match and drops repeated excerpts, so `fragments` can hold several, each with the line it starts on, and `raw` is the list of GitLab results that the match keeps. When the excerpts of a file span two pages, the file comes back on both. ## Activity feeds `repos.events()` reads the events of a project, and `users.events()` the events of a user. A user's events name each project only by ID, so `users.events()` looks up the projects of each page in one GraphQL request and remembers them, as code search does. An event in a project the credential can't read has no `repo` and no `thread`, and the page has a `record_unreachable` warning. A push in a feed names only its last commit, so `detail.commits` holds that commit, while `detail.commitCount` counts every commit of the push. ## Webhooks GitLab doesn't sign the body of a delivery. Instead, it sends the secret token of the hook unchanged in the `X-Gitlab-Token` header, and the provider compares that header with your `webhookSecret`: ```ts const forge = gitlab({ webhookSecret: process.env.GITLAB_WEBHOOK_SECRET, }).create() const events = await forge.webhooks.ingest({ headers: request.headers, body: await request.text(), }) ``` The name of the event is in `X-Gitlab-Event`, and the ID of the delivery is in `X-Gitlab-Event-UUID`. When an update to an issue or merge request changes labels, assignees or reviewers, it becomes one event for each label or person that was added or removed. If there is more than one event, the ID of each is the ID of the delivery followed by `:` and the index of the event. If you create a hook with `webhooks.create()`, `nativeEvents` takes the names of GitLab's event flags, such as `issues_events`. ## Organisation teams GitLab has no teams, so a subgroup stands in for one. `orgs.teams()` reads `GET /groups/{id}/descendant_groups` and lists every subgroup of a group, nested ones included, which GitLab serves for a public group without a credential. A nested subgroup's `parent` is the subgroup it belongs to. `orgs.teamMembers()` reads `GET /groups/{id}/members`, which lists the subgroup's direct members but not those it inherits from the groups above it, and needs a token. It addresses the subgroup by the ref's `id`. The `slug` is the subgroup's path below the group, so for a ref with only the group `acme` and the slug `platform/web`, it reads `GET /groups/acme%2Fplatform%2Fweb/members`. ## Capabilities

Capability	Support	Without credentials
`experimental`	❌	❌
`sources.poll`	✅	❌
`sources.webhook`	✅	✅
`sources.subscribe`	❌	❌
`repos.get`	✅	✅
`users.get`	✅	✅
`users.me`	✅	❌
`users.sponsorable`	❌	❌
`users.events`	✅	✅
`repos.list`	✅	❌
`repos.byOwner`	✅	✅
`repos.labels`	✅	❌
`repos.createLabel`	✅	❌
`repos.milestones`	✅	❌
`repos.collaborators`	✅	❌
`repos.contributors`	✅	✅
`repos.contributorStats`	❌	❌
`repos.templates`	✅	✅
`repos.permissionFor`	✅	❌
`repos.addCollaborator`	✅	❌
`repos.assignableUsers`	✅	✅
`repos.reviewerCandidates`	emulated	emulated
`repos.events`	✅	✅
`orgs.teams`	✅	✅
`orgs.teamMembers`	✅	❌
`threads.get`	issue, PR, commit	issue, PR, commit
`threads.list`	issue, PR	issue, PR
`threads.getMany`	✅	✅
`threads.events`	issue, PR, commit	❌
`comments.list`	issue, PR, commit	commit
`comments.get`	issue, PR, commit (emulated)	commit (unverified)
`comments.edit`	issue, PR	❌
`comments.delete`	issue, PR	❌
`reactions.list`	issue, PR	issue, PR
`notifications.list`	✅	❌
`notifications.markRead`	❌	❌
`notifications.markDone`	✅	❌
`notifications.unsubscribe`	✅	❌
`notifications.markAllRead`	❌	❌
`notifications.markAllDone`	✅	❌
`notifications.unreadCount`	✅	❌
`writes.comment`	issue, PR, commit	❌
`writes.upsertComment`	issue (emulated), PR (emulated)	❌
`writes.close`	issue, PR	❌
`writes.reopen`	issue, PR	❌
`writes.create`	issue, PR	❌
`writes.update`	issue, PR	❌
`writes.setLabels`	issue, PR	❌
`writes.addLabels`	issue, PR	❌
`writes.removeLabels`	issue, PR	❌
`writes.setMilestone`	issue, PR	❌
`writes.react`	issue, PR	❌
`writes.setAssignees`	issue, PR	❌
`writes.requestReview`	PR	❌
`writes.merge`	✅	❌
`writes.approveAndMerge`	✅	❌
`writes.transfer`	✅	❌
`writes.markDuplicate`	emulated	❌
`subscriptions.get`	issue, PR	❌
`subscriptions.set`	issue, PR	❌
`installations`	❌	❌
`checks.thread`	PR	PR
`checks.list`	✅	❌
`checks.get`	❌	❌
`checks.report`	✅	❌
`checks.rerun`	✅	❌
`ci.runs`	✅	✅
`ci.run`	✅	✅
`ci.jobs`	✅	✅
`ci.job`	✅	emulated
`ci.log`	✅	❌
`contents.file`	✅	✅
`contents.tree`	✅	✅
`contents.branches`	✅	✅
`contents.tags`	✅	✅
`contents.resolveRef`	✅	✅
`contents.commits`	✅	✅
`contents.commit`	✅	✅
`contents.compare`	✅	✅
`contents.commitFiles`	✅	❌
`contents.threadFiles`	✅	✅
`contents.threadCommits`	✅	✅
`reviews.list`	emulated	emulated
`reviews.get`	emulated	emulated
`reviews.create`	emulated	❌
`reviews.submit`	❌	❌
`reviews.approve`	✅	❌
`reviews.reply`	✅	❌
`reviews.resolveThread`	✅	❌
`releases.list`	✅	✅
`releases.get`	✅	✅
`releases.latest`	✅	✅
`releases.getByTag`	✅	✅
`releases.downloadAsset`	❌	❌
`releases.create`	✅	❌
`releases.update`	✅	❌
`webhooks.list`	✅	❌
`webhooks.create`	✅	❌
`webhooks.update`	✅	❌
`webhooks.delete`	✅	❌
`webhooks.rotateSecret`	✅	❌
`webhooks.deliveries`	❌	❌
`webhooks.redeliver`	❌	❌
`search.threads`	✅	✅
`search.repos`	✅	✅
`search.commits`	experimental	❌
`search.code`	✅	❌
`securityAlerts`	dependency, code scanning, secret	❌
`eventKinds`	heuristic	heuristic
`authKinds`	`token` , `anonymous`	`token` , `anonymous`
`limits`	body 1048576, comment 1000000, label 255	body 1048576, comment 1000000, label 255

## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.