Skip to content

For the complete documentation index, see llms.txt.

GitLab merge requests

A GitLab merge request trigger starts documentation work from merge requests in the GitLab projects you monitor. When a merge request in a monitored project opens or merges, Promptless reads its code diff, title, and description. If the changes need a documentation update, Promptless creates documentation suggestions.

Promptless skips a merge request whose changes are all in dot-directories, such as .gitlab/ and .gitlab-ci/, or in root-level dot-files, such as .gitignore and .gitlab-ci.yml. These files typically hold CI and tooling configuration. A merge request that changes regular source files along with dot-files gets the normal analysis.

  • An admin role in your Promptless organization, to connect GitLab and edit the Configuration page.
  • The GitLab group that holds the projects you want to monitor, connected to Promptless. Promptless can’t save a GitLab merge request trigger until it is. If the group isn’t connected yet, connect it first.

Skip this section if the group already has a card on the Integrations page.

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.

  1. On the Configuration page, switch to YAML mode.

  2. In the triggers section, add a gitlab_mr trigger with a match clause for the projects you want to monitor:

    triggers:
    gitlab-mrs:
    trigger_type: gitlab_mr
    match:
    - repos:
    - acme/backend
    - acme/api
    trigger_on:
    - opened
    - merge
    trigger_directories:
    - src/
  3. Save the configuration.

Each match clause takes these fields:

FieldRequiredDescription
reposYesThe GitLab projects to monitor, or the literal all.
trigger_onYesThe merge request events that start an analysis: opened, merge, or both.
trigger_directoriesNoOnly merge requests that change files in these directories trigger documentation updates.
branchesNoOnly merge requests that target these branches trigger documentation updates. Omit it to match any.

For every field, including project exclusions, see the Configuration Reference.

The trigger_on list sets when Promptless analyzes a merge request:

  • opened: The merge request opens, reopens, or is marked ready. Promptless skips draft merge requests until they’re marked ready.
  • merge: The merge request merges.

New commits and edits to an open merge request don’t start an analysis. To have Promptless analyze the final changes, include merge in trigger_on.

The trigger form lists a GitLab project only after Promptless confirms that the project has a working Promptless webhook. Promptless adds and checks these webhooks itself on each project where your GitLab token has the Maintainer role. See Token scope considerations. Pick projects from the list, or select All webhook-enabled repositories to watch every listed project.

To see how many projects have a confirmed webhook, check your GitLab connection’s card on the Integrations page. After each check, the card shows a count such as 3 of 4 project webhooks active and when Promptless last checked. If a project you need is missing from the trigger form:

  • If the card shows Webhook verification pending, Promptless hasn’t checked the webhooks yet. Select Check now on the card, or wait for the daily connection check.
  • If fewer webhooks are active than the card’s project count, select Check and repair or Try setup again on the card.
  • If the card doesn’t count the project, the token might lack the Maintainer role on it. Raise the token’s role in GitLab. For a project added after you connected, select Refresh access on the card.

To catch up on merge requests that opened or merged before you configured the trigger, run a backfill from the saved trigger. Review the first batch of suggestions to calibrate Promptless with your documentation style before you go live.

Each saved GitLab merge request trigger on your Configuration page shows when Promptless last received a webhook from the trigger’s projects. Its color shows how long ago:

ColorLast webhook received
GreenWithin the last 4 days
YellowBetween 4 and 14 days ago
Red14 or more days ago

A red status, or “No webhook recorded yet” on a trigger whose projects have recent merge requests, means webhooks probably aren’t reaching Promptless. Check Token scope considerations and Fix common connection problems.

Set where Promptless reports suggestions from this trigger, and how far it automates publishing, in your policies:

OptionPolicy settingEffect
Source MR commentspublishing.suppress_source_pr_commentsPosts a summary comment on the source merge request that links to its documentation suggestions. On by default; set the field to true to turn it off.
Slack notificationsnotification.slack_channelPosts suggestion notifications to a Slack channel. Turning off source MR comments doesn’t affect them.
Automatic PR creationpublishing.auto_create_prOpens a documentation PR for each suggestion.

With source MR comments on, reviewers see proposed documentation updates while they review the code changes.

Request documentation via merge-request comments

Section titled “Request documentation via merge-request comments”

To ask for documentation work on a specific merge request, tag Promptless in a comment on it. A comment mention is an explicit request. Promptless reviews that merge request even when its project isn’t in any of your triggers’ repo lists. Your GitLab connection only needs access to the project. GitHub supports the same request through PR comments.

Comment mentions are useful when:

  • The merge request predates your trigger setup.
  • You want documentation for a merge request that’s already merged or closed.
  • The automatic trigger didn’t activate.
  • You want to give specific instructions about what to document.

What Promptless does depends on the merge request you comment on:

Merge requestWhat Promptless does
One Promptless opened for your documentationRevises that documentation suggestion.
Any other merge requestStarts a new documentation review of that merge request.

Promptless responds to a mention whether the merge request is open, merged, or closed. A mention from an automated account, such as a CI job’s service account, counts the same as one from a teammate.

Post a new comment that tags @promptless anywhere in its text. Matching is case-insensitive. In OSS projects, tag @promptless-for-oss.

@promptless please update the docs for this API change

GitLab also recognizes /promptless at the start of a comment line, but @promptless is more reliable. If /promptless doesn’t get a response, tag @promptless.

Promptless reads mentions in new comments only. Mentions in a comment edit or in the merge request’s title or description don’t start documentation work.

When you tag @promptless in a comment on a merge request, Promptless adds a 👀 reaction to your comment. The reaction appears on both source merge requests and merge requests Promptless opened for your documentation. It shows up even when Promptless decides no documentation change is needed, so a missing suggestion doesn’t mean Promptless ignored your mention.

On an open merge request, Promptless acts on replies in a discussion where it has already commented. You don’t need to mention it. An organization setting decides whether other comments need a mention. An admin can change it in Settings → Organization:

  • Listen to all comments: Promptless acts on comments from people on merge requests linked to a suggestion. These include merge requests it opened for your documentation. It also acts on comments on any other open merge request it opened or commented on.
  • Require a mention: Other comments need a mention.

To keep Promptless from acting on a comment, start it with aside or /aside. To make sure Promptless acts on a comment from an automated account, mention it. For details, see Talk to Promptless without a mention.