GitLab integration

Used for: Triggers, Context, and Publishing

Promptless connects to GitLab in two directions. Promptless uses a GitLab group access token to pull information from GitLab — merge requests, repository files, and project metadata. GitLab uses webhooks to notify Promptless when merge requests change. Promptless requests a group access token (not a project access token), so a single group connection covers all three jobs: triggers, context, and publishing. Promptless supports both gitlab.com and self-hosted GitLab.

Installation

Setup has two parts: create a group access token in GitLab, then connect it in Promptless.

1. Create a GitLab group access token. You need the Owner role for the group, since GitLab restricts group access token creation to group Owners. If you don’t have it, ask a group Owner to create the token. In GitLab, go to your group’s Settings > Access Tokens and click Add new token, then:

   • Name it (for example, “Promptless”).
   • Set an expiration date (maximum one year).
   • Select the api scope.
   • Choose the Maintainer role.

   Click Create group access token and copy it immediately. GitLab shows it only once. The token starts with glpat-. For more details, see GitLab’s group access token documentation.

2. Open the Integrations page in the Promptless dashboard.

3. Start the GitLab connection. For a gitlab.com group, find the Connect GitLab tile and click Connect. For a self-hosted instance, use the Connect self-hosted GitLab tile instead and enter your Instance hostname — just the host, no https:// and no path (for example, gitlab.acme.com).

4. Paste the token into the Group Access Token field and click Connect.

Required Scope

The token must be a group access token with the api scope and the Maintainer role. Tokens without the api scope don’t work with Promptless, and Maintainer is required because webhook creation is Maintainer-gated. GitLab has no read-only token option — see Token scope considerations for why.

Connect multiple GitLab groups

A GitLab group access token grants access to one group and its subgroups, so to cover more than one top-level group you connect one token per group. Connecting a second group doesn’t replace the first — every group you connect stays active. You can connect any combination: sibling or nested (subgroup) groups, and groups on different GitLab instances (gitlab.com and self-hosted). To add another group, click Connect GitLab (or Connect self-hosted GitLab) again on the Integrations page and repeat the installation steps with that group’s token.

Connected groups

Each connected group appears as its own card on the Integrations page. Each card is titled GitLab (gitlab.com) for a gitlab.com connection, or GitLab · <host> for a self-hosted instance. Every card shows a Host: line (gitlab.com for a gitlab.com connection, or the self-hosted domain) and a Group: line with the connected group. The card lists the connected group’s projects by full path (for example, promptless-engineers/<repo>), sorted alphabetically.

The card’s manual Refresh re-syncs the project inventory. Projects added to a group after you connect it appear only after you refresh.

Project setup

After connecting your GitLab account, you can configure how Promptless interacts with your projects:

Repository access

When setting up a project with GitLab as a trigger source:

1. Select the GitLab projects you want Promptless to monitor for changes.
2. Optionally, configure directory-specific triggers to focus on particular parts of your codebase.

Directory-specific triggers

You can configure Promptless to only trigger documentation updates when changes are made to specific directories in your GitLab projects. This is useful for:

• Focusing on code that directly impacts user-facing features
• Monitoring API changes that require documentation updates
• Ignoring internal tooling or test changes that don’t affect documentation

To set up directory-specific triggers:

1. In your project configuration, select the GitLab project.
2. Under Advanced Options, enable Directory-Specific Triggers.
3. Enter the directories you want to monitor, separated by commas (for example, src/api, docs/reference).

Merge request link resolution

When you share a GitLab.com merge request link in a Slack message or other trigger, Promptless automatically fetches the MR content. This includes:

• MR metadata (title, state, source/target branches, author)
• Discussion comments with file positions and resolved state
• The full diff for analysis

This allows Promptless to gather context from linked merge requests.

Note

Merge request link resolution currently works only for gitlab.com. Self-hosted GitLab instances are supported for webhook-based triggers but not for link resolution.

Source code reading

Promptless can read source files directly from your GitLab projects when processing merge requests or researching documentation updates. This provides context from implementation details that aren’t visible in merge request diffs alone.

Promptless uses the GitLab CLI (glab) to fetch file contents from your repositories. This is useful when:

• A merge request references code in files that weren’t changed
• A new feature needs to be understood in the context of existing code
• Documentation requires accurate details about implementation behavior

Note

Source code reading works with gitlab.com projects. Self-hosted GitLab instances support webhook-based triggers but not source code reading.

Publishing documentation to GitLab

Beyond triggers and context, 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, pushes that branch, and opens a merge request for you to review, the same way it opens pull requests on GitHub.

To publish to GitLab, your connected group access token needs the write-capable api scope—the same scope the integration already uses for triggers. Promptless writes only to the projects you set up as doc collections.

GitLab doc collections work on both gitlab.com and self-hosted GitLab, and both are set up the same way. The project picker lists your connected GitLab projects across every connected instance, and a GitLab host field on the same form takes your self-hosted hostname — leave it blank for gitlab.com. See GitLab projects for setup details and the configuration reference for the platform: gitlab and host fields.

Promptless tracks merge request status the same way it tracks GitHub pull request status. Because GitLab has no draft flag at creation time, Promptless marks a draft merge request with a Draft: title prefix.

Auto-merge differs from the GitHub path—on GitLab, Promptless attempts the merge immediately instead of waiting for a pipeline—so see Automatic merge request creation before you enable it.

Authentication model

The GitLab integration authenticates with a group access token:

• Group Access Token: A token with the api scope for full API access.
• Webhook Triggers: Work with both gitlab.com and self-hosted GitLab instances.
• Publishing (doc collections): Works with both gitlab.com and self-hosted GitLab instances.
• Link Resolution: Works with gitlab.com only.
• Source Code Reading: Works with gitlab.com only.

The token’s scope and role limit what Promptless can do; see Token scope considerations for which projects it can reach and why Promptless enforces the per-project boundary rather than the token.

Token scope considerations

GitLab has no read-only option. Connecting a GitLab group always performs writes with the group access token: it creates the merge-request webhooks across the group’s projects, and it also sets the Promptless bot avatar as an incidental additional write. Webhook creation is the hard blocker — a read-only (read_api) token cannot create those webhooks, so the integration delivers no merge-request triggers and is connected but inert. Unlike the GitHub (read-only) app, GitLab has no read-only equivalent, so even a triggers-and-context-only setup needs a write-capable token.

The group access token needs the api scope and the Maintainer role. This is what the connect flow recommends and what a working connection requires. Maintainer is required because connecting a group always sets up the merge-request webhooks across the group’s projects, and creating those webhooks requires the Maintainer role. Publishing on its own — pushing a branch and opening a merge request — needs only lower privilege (at least the Developer role for those write operations), but because every connection sets up webhooks, Maintainer is the effective requirement for any GitLab connection, whether you use it as a trigger and context source, a docs destination, or both. A Developer-role token completes the initial connect but receives no webhooks (the failure is swallowed silently) and then hard-fails on the next refresh, so it is not a viable option. The clean, safe recommendation is api scope with the Maintainer role.

Promptless writes only to the projects you configure as doc collections. That’s an application-level restriction Promptless enforces — the token itself doesn’t impose it.

Two layers limit what Promptless can reach. The first is a hard, token-level limit: if you scope the group access token to a group or subgroup that contains only your documentation projects, the token can’t reach anything outside it. Scoping the token to a documentation-only subgroup is safe only when your trigger and context source projects and your docs-destination projects all live within that same group or subgroup — otherwise the token can’t reach source projects outside it. The second is an application-level path scope on the doc collection, which limits which files Promptless can change.

Webhook management

Promptless automatically sets up webhooks in your GitLab projects to monitor for merge request events. These webhooks:

• Trigger Promptless when merge requests are created or updated
• Send only the necessary information about changes to Promptless
• Can be customized to focus on specific events

Usage

Once configured, the GitLab integration works similarly to other code hosting integrations:

1. When a merge request is opened or updated in your monitored projects, Promptless is automatically triggered.
2. Promptless analyzes the changes to determine if documentation updates are needed.
3. If updates are needed, Promptless generates the appropriate documentation changes.
4. Promptless adds a comment to your GitLab merge request with a link to review the documentation changes.
5. You can review and approve the suggested documentation updates in the Promptless dashboard.

For more information on how triggers work in general, see the Triggers documentation.