GitLab integration
Overview
Section titled “Overview”Connect a GitLab group to Promptless so it can start documentation work from your merge requests, read your code for context, and publish documentation updates. Promptless supports both gitlab.com and self-hosted GitLab.
The connection works in two directions. Promptless uses a GitLab group access token to pull merge requests, repository files, and project metadata from GitLab. GitLab uses webhooks to notify Promptless when merge requests change. Because the token belongs to a group, one connection covers triggers, context, and publishing for that group’s projects:
| Capability | What Promptless does | gitlab.com | Self-hosted GitLab |
|---|---|---|---|
| Merge request triggers | Reviews merge requests that open or merge in monitored projects, and suggests documentation changes. | Yes | Yes |
| Merge request link resolution | Fetches a merge request’s content when you share its link in a Slack message or other trigger. | Yes | No |
| Source code reading | Reads files from your projects for context that a merge request diff doesn’t show. | Yes | No |
| Publishing | Opens merge requests with documentation updates in projects you set up as doc collections. | Yes | Yes |
Merge request link resolution fetches the title, state, source and target branches, author, discussion comments with file positions and resolved state, and the full diff. Source code reading uses the GitLab CLI (glab) to fetch files that a merge request references but doesn’t change. Promptless uses them to describe existing code and implementation behavior accurately.
In this guide, you create a group access token, connect it in Promptless, and then set up merge request triggers and publishing.
Before you start
Section titled “Before you start”- The Owner role on the GitLab group. GitLab restricts group access token creation to group Owners, so if you don’t have the role, ask a group Owner to create the token.
- An admin role in your Promptless organization. Only organization admins can connect integrations.
- For a self-hosted instance, its hostname, such as
gitlab.acme.com.
Token requirements
Section titled “Token requirements”The GitLab integration authenticates with a group access token that meets these requirements:
| Requirement | Value | Why |
|---|---|---|
| Token type | Group access token | One token covers a group and its subgroups. GitLab lets only group Owners create one. |
| Scope | api | Promptless checks the scope when you connect and rejects a token without it. |
| Role | Maintainer (by project) | Promptless installs merge-request webhooks only on projects where the token has the Maintainer role. |
Token scope considerations
Section titled “Token scope considerations”The token needs the api scope. GitLab has no read-only option that works with Promptless. Promptless checks the scope when you connect and rejects a read_api token, because that token can’t open merge requests or install webhooks. Promptless offers a GitHub (read-only) app, but GitLab has no equivalent. Even a setup that uses GitLab only for triggers and context needs the write-capable api scope.
The token’s role on each project decides what Promptless can do in that project. The token connects whatever its role in the group is, because Promptless checks its role on each project separately. A direct membership on a project counts, so the token can have a higher role on a project than in its group.
| Token’s role on the project | What works there |
|---|---|
| Maintainer or Owner | Merge request triggers, context, and publishing. Promptless adds the webhook itself. |
| Developer | Context and publishing |
| Reporter | Context |
Merge request triggers need a webhook on the project. Where the token’s role is below Maintainer, raise it to Maintainer on that project, or add the webhook in GitLab yourself.
Two layers limit what Promptless can reach:
- The token’s group is a hard, token-level limit. A group access token scoped to a group or subgroup that contains only your documentation projects can’t reach anything outside it. That setup works only when your trigger and context source projects live in the same group or subgroup as your documentation projects. Otherwise the token can’t reach the source projects.
- The doc collection is an application-level limit. Promptless enforces it, and the token doesn’t. Promptless writes only to the projects you configure as doc collections, and a doc collection’s path scope limits which files Promptless can change.
Connect a GitLab group
Section titled “Connect a GitLab group”You need the Owner role on the GitLab group to create its access token, and an admin role in your Promptless organization to connect it. If you aren’t a group Owner, ask one to create the token.
Create a token that only Promptless uses. Promptless counts every merge request the token opens as its own and skips it as a trigger event.
-
In GitLab, go to your group’s Settings > Access Tokens and select Add new token.
-
Name the token, for example “Promptless”, and set an expiration date. The maximum is one year.
-
Select the
apiscope and the Maintainer role. Promptless installs merge-request webhooks only on projects where the token has the Maintainer role. -
Select Create group access token, and copy the token. GitLab shows it only once. The token starts with
glpat-. For more details, see GitLab’s group access token documentation. -
In the Promptless dashboard, open the Integrations page.
-
Start the connection. For a gitlab.com group, select Connect GitLab on the GitLab tile. For a self-hosted instance, select Connect Self-hosted GitLab on the Self-hosted GitLab tile, and enter your Instance hostname. Enter only the host, with no
https://and no path. -
In the Group path field, enter the group’s full path, for example
acme/platform. -
Paste the token into the Access token field, and select Connect.
The token must be a group access token with the api scope. Promptless checks the scope when you connect and rejects a token without it. For why, see Token scope considerations.
The group gets its own card on the Integrations page. To connect another group, select Connect GitLab or Connect Self-hosted GitLab again and repeat these steps with that group’s token.
The group’s card lists its projects by full path, for example promptless-engineers/<repo>. Promptless sets up webhooks automatically in the group’s projects where the token has the Maintainer role. Each webhook subscribes to these GitLab events:
| GitLab event | What Promptless does with it |
|---|---|
| Merge request events | Starts a review when a merge request opens or merges. |
| Comments | Picks up merge request comments that mention Promptless, so a tagged comment can request documentation work. See Request documentation via merge-request comments. |
If a Promptless webhook is missing either event, Promptless restores it the next time it syncs the group’s webhooks.
Connect more GitLab groups
Section titled “Connect more GitLab groups”A group access token grants access to one group and its subgroups. To cover more than one top-level group, connect one token per group. Every group you connect stays active. You can connect sibling or nested groups, and groups on different GitLab instances, both gitlab.com and self-hosted.
Refresh a group’s project list
Section titled “Refresh a group’s project list”Promptless reads a group’s project list when you connect the group.
- To pick up projects added to the group later, select Refresh access on the group’s card on the Integrations page.
Add merge request triggers
Section titled “Add merge request triggers”Choose which projects start documentation work by adding a GitLab merge request trigger and selecting its projects. The trigger form lists only projects where Promptless has confirmed its webhook. See Project selection. To trigger only on changes in specific directories, such as src/api or docs/reference, fill in Only when files in these folders change on the trigger (trigger_directories in YAML). Use it to focus on user-facing code and API changes, and to skip internal tooling and test changes.
For which merge request events start an analysis, see Trigger events. When a merge request opens or merges in a monitored project, Promptless runs automatically:
- Promptless analyzes the changes to determine whether documentation needs updates.
- If it does, Promptless generates the documentation changes.
- Promptless comments on the merge request with a link to review the documentation changes.
- You review and approve the suggested updates in the Promptless dashboard.
For how triggers work in general, see Triggers.
Publish documentation to GitLab
Section titled “Publish documentation to GitLab”A GitLab project can also be a doc collection: a place where your documentation lives and where Promptless publishes updates. When documentation needs to change, Promptless clones the project, edits files on a new branch, and pushes that branch. It then opens a merge request for you to review, the same way it opens pull requests on GitHub. Publishing uses the api scope the group access token already has.
GitLab doc collections work on both gitlab.com and self-hosted GitLab, and you set them up the same way. The project picker lists your connected GitLab projects across every connected instance. For a self-hosted project, enter its hostname in the GitLab host field. Leave the field blank for gitlab.com. For setup details, see GitLab projects. For the platform: gitlab and host fields, see the configuration reference.
Promptless tracks merge request status the same way it tracks GitHub pull request status. GitLab has no draft flag at creation time, so Promptless marks a draft merge request with a Draft: title prefix.
With auto-merge on, Promptless attempts the merge immediately. If GitLab can’t merge it yet, for example because a required pipeline hasn’t passed, the merge request stays open for you to merge. See Automatic merge request creation before you enable it.
Fix common connection problems
Section titled “Fix common connection problems”| Problem | Cause | Fix |
|---|---|---|
| Promptless rejects your token when you connect. | The token is missing the api scope. | Create a token with the api scope, then connect again. |
| The group connected, but no merge request triggers arrive from a project. | Promptless installs merge-request webhooks only on projects where the token has the Maintainer role. | Raise the token’s role on that project to Maintainer, or add the webhook in GitLab by hand. |
| A project you added to the group doesn’t appear under the connected group. | Promptless reads the project list when you connect a group, so it doesn’t show projects added later. | Select Refresh access on the group’s card on the Integrations page. |
For why GitLab has no read-only option and how the Maintainer role controls webhooks, see Token scope considerations.
See also
Section titled “See also”- GitLab merge requests, to configure which merge requests start documentation work
- GitLab projects, to set up a GitLab project as a doc collection
- Source control and access scope, to compare GitHub, GitHub Enterprise, and GitLab connections