GitLab projects

Tip

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

You can store your documentation in a GitLab project and have Promptless publish updates there. This docs-as-code approach keeps your documentation under version control alongside the rest of your work, and it supports both gitlab.com and self-hosted GitLab.

Note

Prerequisite: Before creating a GitLab-based doc collection, you must first connect GitLab on the integrations page. The connected group access token must have the write-capable api scope so Promptless can push a branch and open a merge request. If the repository picker is missing or lists no GitLab projects, either GitLab isn’t connected yet or the group token’s project inventory doesn’t include the project you want; the GitLab integration page covers connecting GitLab and scoping the token to the right group.

How it works

1. Project setup: Your documentation files live in a GitLab project.
2. Promptless access: Promptless reaches the project using your connected GitLab group access token, which needs the api scope.
3. Automatic merge requests: When documentation updates are needed, Promptless pushes a branch directly to your docs project—there’s no fork step, unlike the GitHub open-source flow—and opens a merge request.
4. Platform sync: Your documentation platform automatically syncs changes from GitLab.

Configuration

Add a GitLab doc collection on the Doc collections tab of the Configuration page.

Under Which repository should Promptless document?, the picker lists your connected GitHub and GitLab repositories, or you can type a repository path. Type the project’s full path including every namespace segment, such as acme/platform/developer-docs for a project in a nested subgroup. Every connected GitLab project appears here—gitlab.com and self-hosted alike—so a self-hosted project needs no special path through the configuration editor.

You don’t pick a platform. Promptless derives it from the connection that reaches the repository and shows the result as read-only text under Where this repo lives: “GitLab — Promptless opens merge requests on this project directly.”

The GitLab host field tells Promptless which instance to reach. Leave it blank for gitlab.com. For self-hosted GitLab, enter just the hostname—no https:// and no path—such as gitlab.acme.com.

The rest of the form matches a GitHub doc collection: your docs framework, published URL, and the directories Promptless can modify.

In YAML, a GitLab collection sets platform: gitlab and is keyed by the project’s full path, including every namespace segment:

doc_collections:
  acme/docs:                              # gitlab.com project
    platform: gitlab
    docs_framework: docusaurus
  acme/platform/developer-docs:           # self-hosted, nested namespace
    platform: gitlab
    host: gitlab.acme.com
    docs_framework: mkdocs

See the configuration reference for every field a doc collection accepts.

Automatic merge request creation

When automatic PR creation (auto_create_pr) is enabled in your publishing policies, Promptless opens a merge request in your documentation project with the suggested changes. Merge request status is tracked the same way GitHub pull request status is. Because GitLab has no draft flag at creation time, Promptless marks a draft merge request with a Draft: title prefix.

When Promptless opens or updates a merge request, the suggestion’s citations post as diff-positioned discussion threads on the merge request itself—not only in the dashboard—so reviewers see each source at the line it supports. A citation that can’t be anchored to the diff falls back to an unanchored merge-request thread that names the file and line.

You can also enable automatic merging (auto_merge) in your publishing policies to have Promptless merge its documentation changes automatically. On GitLab, Promptless attempts an immediate squash merge as soon as it opens the merge request. See Policies for how publishing rules resolve.

GitLab auto-merge does not wait for pipelines

GitLab auto-merge behaves differently from the GitHub auto-merge path. Promptless deliberately does not use GitLab’s “merge when pipeline succeeds”—it attempts the merge right away, does not wait for a pipeline, and does not retry later. The merge request might not be able to merge at that moment—for example, a required pipeline hasn’t passed, approvals are pending, or there are conflicts. When that happens, GitLab reports a failure and Promptless leaves the merge request open for you to merge manually.

Path scope (documentation directories)

Path scope controls which files Promptless can modify in your documentation project, exactly as it does for GitHub repositories. When you specify directories during doc collection setup, Promptless enforces these boundaries:

• All files allowed (default): If no directories are specified, Promptless can create and modify files anywhere in the project.
• Scoped to specific paths: When directories are specified, Promptless can only modify files that match one of those paths exactly or are nested inside one of those directories.

Path scopes support both directories and individual files. A scope entry like CHANGELOG.md allows only that specific file, while docs/ allows any file under that directory. When Promptless creates a suggestion with changes outside the configured scope, the suggestion is rejected with an error listing which files are out of scope.

Setup instructions

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