GitLab merge requests

Tip

You can set up this trigger by hand as this page describes, or ask Promptless in Slack or Microsoft Teams to do it for you. For example, “@Promptless add a GitLab merge request trigger for my acme/backend project.” See Ask Promptless to update your configuration.

Promptless monitors your GitLab projects for merge requests. When a merge request is opened or updated, Promptless analyzes the changes and creates documentation suggestions if needed.

How it works

When a merge request event occurs in your monitored GitLab projects:

1. Automatic Detection: Promptless receives notification of the new or updated merge request.
2. Analysis: The system processes the code diff, MR title, and MR description to understand the context.
3. Relevance Assessment: Promptless determines if the changes require documentation updates.
4. Suggestion Creation: If relevant, Promptless creates documentation suggestions.

Note

Information from merge requests is processed in real-time and not stored by Promptless. The analysis happens only when the configured trigger event occurs.

Configuration

Note

Adding, renaming, or modifying a GitLab merge request trigger requires the GitLab integration to be connected first. See Connect a provider before you add its triggers.

Configure GitLab merge request triggers in your Configuration page using the triggers section:

triggers:
  gitlab-mrs:
    trigger_type: gitlab_mr
    match:
      - repos:
          - acme/backend
          - acme/api
        trigger_on:
          - opened
          - merge
        trigger_directories:
          - src/

See the Configuration Reference for all available options.

Webhook delivery status

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

• Green: within the last 4 days.
• Yellow: 4 or more days ago.
• Red: 14 or more days ago.

A red box, 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 the GitLab integration FAQ.

Replay recent merge requests

When setting up a new GitLab MR trigger, you can enable “Replay recent MRs” to process merge requests from the last 30 days. This generates an initial batch of suggestions, which helps you:

• Calibrate Promptless with your documentation style before going live
• Catch up on documentation that may have been missed
• Evaluate how Promptless handles your typical MR content

After enabling this option, your Project card shows the replay progress:

• Processing last 30 days of MRs with a spinner while replay is running
• Processed recent MRs with a checkmark once replay completes

Note

Replay runs in the background and doesn’t block normal trigger processing. New MRs opened while replay is running are still processed immediately.

Directory-specific triggers

Use the trigger_directories field to only trigger when changes are made to specific directories. When specified, Promptless considers only merge requests that contain changes to those directories.

Automatic PR creation

When automatic PR creation is enabled in your publishing policies, Promptless automatically creates a new PR in your documentation repository with suggested changes.

Source MR comments

Promptless posts a summary comment on source merge requests linking to any documentation changes. This keeps documentation updates visible alongside the code changes that triggered them.

The comment links directly to the documentation suggestions, so reviewers can see proposed updates while reviewing the code.

Tip

Slack notifications are separate from source MR comments and are always sent according to your project’s notification settings.

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.

How to use

Post a comment that tags @promptless anywhere in its text. Matching is case-insensitive. OSS projects use @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, use @promptless instead.

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

What happens

• On a merge request Promptless opened for your documentation, the comment revises that documentation suggestion.
• On any other merge request, the comment 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.

When to use

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.

Comment mention acknowledgment

When you @mention @promptless in a comment on a merge request, Promptless adds a 👀 reaction to your comment so you know it saw the request. This works for comments on both a source merge request and a merge request Promptless opened for your documentation.

Note

The reaction shows up even when Promptless decides no documentation change is needed, so a missing suggestion doesn’t mean your mention was ignored.

Respond to comments on documentation merge requests

Comments on a merge request Promptless opened for your documentation honor your organization’s comment trigger mode, Listen to all comments or Require @promptless mentions. Tagging @promptless (or using a line-leading /promptless) always ensures Promptless acts on a comment, including comments from automated accounts.

Promptless handles unmentioned comments this way only on merge requests it opened for your documentation. Other merge requests always require a mention.

Configuration files and dot-directories

Promptless automatically skips merge requests that only contain changes to dot-directories (like .gitlab/, .gitlab-ci/) or root-level dot-files (like .gitignore, .gitlab-ci.yml). These are typically CI and tooling configuration rather than product changes that need documentation updates.

If an MR contains both dot-files and regular source files, Promptless processes it normally. It only skips when the entire MR is dot-file changes.

Setup instructions

To connect GitLab to Promptless, see the GitLab Integration setup guide.