GitLab merge requests
Overview
Section titled “Overview”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.
Before you start
Section titled “Before you start”- 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.
Connect a GitLab group
Section titled “Connect a GitLab group”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.
-
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.
Add a merge request trigger
Section titled “Add a merge request trigger”-
On the Configuration page, switch to YAML mode.
-
In the
triggerssection, add agitlab_mrtrigger with a match clause for the projects you want to monitor:triggers:gitlab-mrs:trigger_type: gitlab_mrmatch:- repos:- acme/backend- acme/apitrigger_on:- opened- mergetrigger_directories:- src/ -
Save the configuration.
Each match clause takes these fields:
| Field | Required | Description |
|---|---|---|
repos | Yes | The GitLab projects to monitor, or the literal all. |
trigger_on | Yes | The merge request events that start an analysis: opened, merge, or both. |
trigger_directories | No | Only merge requests that change files in these directories trigger documentation updates. |
branches | No | Only merge requests that target these branches trigger documentation updates. Omit it to match any. |
For every field, including project exclusions, see the Configuration Reference.
Trigger events
Section titled “Trigger events”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.
Project selection
Section titled “Project selection”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.
Check webhook delivery status
Section titled “Check webhook delivery status”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:
| Color | Last webhook received |
|---|---|
| Green | Within the last 4 days |
| Yellow | Between 4 and 14 days ago |
| Red | 14 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 how Promptless publishes suggestions
Section titled “Set how Promptless publishes suggestions”Set where Promptless reports suggestions from this trigger, and how far it automates publishing, in your policies:
| Option | Policy setting | Effect |
|---|---|---|
| Source MR comments | publishing.suppress_source_pr_comments | Posts 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 notifications | notification.slack_channel | Posts suggestion notifications to a Slack channel. Turning off source MR comments doesn’t affect them. |
| Automatic PR creation | publishing.auto_create_pr | Opens 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 request | What Promptless does |
|---|---|
| One Promptless opened for your documentation | Revises that documentation suggestion. |
| Any other merge request | Starts 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.
Mention Promptless in a comment
Section titled “Mention Promptless in a comment”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 changeGitLab 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.
Confirm Promptless saw your mention
Section titled “Confirm Promptless saw your mention”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.
Talk to Promptless without a mention
Section titled “Talk to Promptless without a 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.
See also
Section titled “See also”- GitLab integration, for token scope, webhooks, and connection problems
- GitHub PRs, for the equivalent GitHub trigger
- Review and edit Promptless PRs, to give Promptless feedback on the merge requests it opens