GitLab integration

Used for: Triggers, Context

Promptless integrates with GitLab using group access token authentication, monitoring merge requests in your repositories for documentation updates and providing read access to source code for deeper context.

Installation

To set up the GitLab integration:

1. Go to the Integrations page in the Promptless dashboard.
2. Click Connect GitLab.
3. Enter a GitLab group access token with the api scope.
4. Click Connect.

Required Scope

Your GitLab group access token must have the api scope. Tokens without this scope don’t work with Promptless.

Creating a GitLab Group Access Token

To create a group access token with the required permissions:

1. Sign in to your GitLab account.
2. Navigate to your group’s Settings > Access Tokens.
3. Click Add new token.
4. Give it a descriptive name like “Promptless Integration”.
5. Set an expiration date (group access tokens have a maximum 1-year lifespan).
6. Select the api scope.
7. Choose an appropriate role (Developer or higher recommended).
8. Click Create group access token.
9. Copy the token immediately—you won’t be able to see it again.

For more details, see GitLab’s group access token documentation.

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. Choose whether Promptless should have read-only access or write access to your documentation repositories.
3. 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 (e.g., src/api, docs/reference).

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

Authentication model

The GitLab integration uses group access token authentication:

• Group Access Token: A secure token with the api scope for full API access
• Webhook Triggers: Work with both GitLab.com and self-hosted GitLab instances
• Source Code Reading: Works with GitLab.com only

This authentication model ensures that Promptless only has access to the projects and actions you explicitly authorize through the token’s permissions.

Token scope considerations

GitLab group access tokens have read-write api scope by default. Promptless only performs read operations with these tokens: viewing merge requests, reading repository files, and fetching project metadata. Promptless never pushes code, creates merge requests, or modifies your GitLab projects through this token.

Using Read-Only Tokens

If your organization requires stricter access controls, you can provision a group access token with the read_api scope instead of api. This limits the token to read-only operations at the GitLab API level, providing an additional layer of security beyond Promptless’s behavioral restrictions.

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.