Skip to content

For the complete documentation index, see llms.txt.

GitLab integration

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:

CapabilityWhat Promptless doesgitlab.comSelf-hosted GitLab
Merge request triggersReviews merge requests that open or merge in monitored projects, and suggests documentation changes.YesYes
Merge request link resolutionFetches a merge request’s content when you share its link in a Slack message or other trigger.YesNo
Source code readingReads files from your projects for context that a merge request diff doesn’t show.YesNo
PublishingOpens merge requests with documentation updates in projects you set up as doc collections.YesYes

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.

  • 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.

The GitLab integration authenticates with a group access token that meets these requirements:

RequirementValueWhy
Token typeGroup access tokenOne token covers a group and its subgroups. GitLab lets only group Owners create one.
ScopeapiPromptless checks the scope when you connect and rejects a token without it.
RoleMaintainer (by project)Promptless installs merge-request webhooks only on projects where the token has the Maintainer role.

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 projectWhat works there
Maintainer or OwnerMerge request triggers, context, and publishing. Promptless adds the webhook itself.
DeveloperContext and publishing
ReporterContext

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.

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.

  1. In GitLab, go to your group’s Settings > Access Tokens and select Add new token.

  2. Name the token, for example “Promptless”, and set an expiration date. The maximum is one year.

  3. Select the api scope and the Maintainer role. Promptless installs merge-request webhooks only on projects where the token has the Maintainer role.

  4. 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.

  5. In the Promptless dashboard, open the Integrations page.

  6. 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.

  7. In the Group path field, enter the group’s full path, for example acme/platform.

  8. Paste the token into the Access token field, and select Connect.

    Connect GitLab modal with Group path and Access token fields and a Connect button

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 eventWhat Promptless does with it
Merge request eventsStarts a review when a merge request opens or merges.
CommentsPicks 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.

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.

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.

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:

  1. Promptless analyzes the changes to determine whether documentation needs updates.
  2. If it does, Promptless generates the documentation changes.
  3. Promptless comments on the merge request with a link to review the documentation changes.
  4. You review and approve the suggested updates in the Promptless dashboard.

For how triggers work in general, see Triggers.

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.

ProblemCauseFix
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.