Repository navigation
Correct GitLab connect token requirements for the capability preflight - #927
promptless[bot] wants to merge 29 commits into
Conversation
GitLab connect now runs a token-capability preflight: a token that can open merge requests (api scope + at least Developer) connects, one that can't is refused at connect, and a Developer-role token connects with its automatic- webhook limitation recorded on the connection card. Update the GitLab integration reference and add an August changelog entry to match.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
|
|
||
| <Aside type="caution" title="Required Scope"> | ||
| The token must be a **group** access token with the **`api`** scope and the **Maintainer** role. Tokens without the `api` scope don't work with Promptless, and Maintainer is required because webhook creation is Maintainer-gated. GitLab has no read-only token option — see [Token scope considerations](#token-scope-considerations) for why. | ||
| Use a **group** access token. To connect, the token needs the **`api`** scope and at least the **Developer** role — enough for Promptless to push branches and open merge requests. The **Maintainer** role is recommended but not required to connect: it lets Promptless install the merge-request webhooks automatically. See [Token scope considerations](#token-scope-considerations) for what each role covers. |
There was a problem hiding this comment.
api scope + Developer(30) role is the floor to connect: can_push and can_open_merge_requests both use GITLAB_DEVELOPER_ACCESS_LEVEL (30); can_open_merge_requests requires the api scope specifically (GITLAB_API_WRITE_SCOPES). Maintainer(40) is only required for can_manage_hooks.
| ### Token scope considerations | ||
|
|
||
| **GitLab has no read-only option.** Connecting a GitLab group always performs writes with the group access token: it creates the merge-request webhooks across the group's projects, and it also sets the Promptless bot avatar as an incidental additional write. Webhook creation is the hard blocker — a read-only (`read_api`) token cannot create those webhooks, so the integration delivers no merge-request triggers and is connected but inert. Unlike the [GitHub (read-only) app](/docs/for-docs/reference/integrations/github-read-only), GitLab has no read-only equivalent, so even a triggers-and-context-only setup needs a write-capable token. | ||
| GitLab has no **read-only** option. Connecting a GitLab group always performs writes with the group access token: Promptless opens merge requests to publish, installs merge-request webhooks across the group's projects, and sets the Promptless bot avatar as an incidental additional write. A read-only (`read_api`) token lacks the `api` scope. Unlike the [GitHub (read-only) app](/docs/for-docs/reference/integrations/github-read-only), even a triggers-and-context-only GitLab setup needs a write-capable token. |
There was a problem hiding this comment.
GITLAB_API_WRITE_SCOPES=("api",) is the only accepted scope for can_open_merge_requests, so a read_api token (which lacks api) is BLOCKED and refused at connect.
| GitLab has no **read-only** option. Connecting a GitLab group always performs writes with the group access token: Promptless opens merge requests to publish, installs merge-request webhooks across the group's projects, and sets the Promptless bot avatar as an incidental additional write. A read-only (`read_api`) token lacks the `api` scope. Unlike the [GitHub (read-only) app](/docs/for-docs/reference/integrations/github-read-only), even a triggers-and-context-only GitLab setup needs a write-capable token. | ||
|
|
||
| **The group access token needs the `api` scope and the Maintainer role.** This is what the connect flow recommends and what a working connection requires. Maintainer is required because connecting a group always sets up the merge-request webhooks across the group's projects, and creating those webhooks requires the Maintainer role. Publishing on its own — pushing a branch and opening a merge request — needs only lower privilege (at least the Developer role for those write operations), but because every connection sets up webhooks, Maintainer is the effective requirement for any GitLab connection, whether you use it as a trigger and context source, a docs destination, or both. A Developer-role token completes the initial connect but receives no webhooks (the failure is swallowed silently) and then hard-fails on the next refresh, so it is not a viable option. The clean, safe recommendation is `api` scope with the Maintainer role. | ||
| The group access token needs the **`api`** scope and a role of at least **Developer**. That is the floor to connect: with `api` and the Developer role, the token can push branches and open merge requests, which is everything Promptless needs to deliver a documentation change. A token that cannot open merge requests — one that lacks `api`, or that sits below the Developer role — is refused when you connect, with an inline error in the connect modal. The refusal comes before any project is fetched or any webhook written, so nothing is persisted. |
There was a problem hiding this comment.
Preflight (evaluate_gitlab_connect_preflight) runs and can raise HTTP 400 with preflight.blocking_reason (line 413) before gitlab_group_projects is fetched (line 426) and before the installation is persisted (new_installation/replace_gitlab_claim at lines 460-472) — confirms "before any project is fetched or any webhook written, so nothing is persisted."
| **The group access token needs the `api` scope and the Maintainer role.** This is what the connect flow recommends and what a working connection requires. Maintainer is required because connecting a group always sets up the merge-request webhooks across the group's projects, and creating those webhooks requires the Maintainer role. Publishing on its own — pushing a branch and opening a merge request — needs only lower privilege (at least the Developer role for those write operations), but because every connection sets up webhooks, Maintainer is the effective requirement for any GitLab connection, whether you use it as a trigger and context source, a docs destination, or both. A Developer-role token completes the initial connect but receives no webhooks (the failure is swallowed silently) and then hard-fails on the next refresh, so it is not a viable option. The clean, safe recommendation is `api` scope with the Maintainer role. | ||
| The group access token needs the **`api`** scope and a role of at least **Developer**. That is the floor to connect: with `api` and the Developer role, the token can push branches and open merge requests, which is everything Promptless needs to deliver a documentation change. A token that cannot open merge requests — one that lacks `api`, or that sits below the Developer role — is refused when you connect, with an inline error in the connect modal. The refusal comes before any project is fetched or any webhook written, so nothing is persisted. | ||
|
|
||
| Give the token the **Maintainer** role for the clean path. Maintainer lets Promptless install the merge-request webhooks across the group's projects automatically, so merge requests and comment mentions start documentation work without any manual webhook setup. A Developer-role token with `api` still connects: Promptless records the webhook limitation and surfaces it on the connection's card on the Integrations page, and the connection keeps working on later refreshes. To close the gap, add the webhooks by hand in GitLab, or raise the token to Maintainer and use the **Automatic webhooks** control on the connection's card to install them across every accessible project. |
There was a problem hiding this comment.
_blocking_reason only checks can_open_merge_requests (Developer floor), so a Developer-role api token is not refused. The below-Maintainer can_manage_hooks limitation is returned only as a warning (_warnings), which the connect route (devtools.py L414-423) only logs — it is recorded on the persisted token_capability info, not shown as a connect-time user-facing warning.
| **The group access token needs the `api` scope and the Maintainer role.** This is what the connect flow recommends and what a working connection requires. Maintainer is required because connecting a group always sets up the merge-request webhooks across the group's projects, and creating those webhooks requires the Maintainer role. Publishing on its own — pushing a branch and opening a merge request — needs only lower privilege (at least the Developer role for those write operations), but because every connection sets up webhooks, Maintainer is the effective requirement for any GitLab connection, whether you use it as a trigger and context source, a docs destination, or both. A Developer-role token completes the initial connect but receives no webhooks (the failure is swallowed silently) and then hard-fails on the next refresh, so it is not a viable option. The clean, safe recommendation is `api` scope with the Maintainer role. | ||
| The group access token needs the **`api`** scope and a role of at least **Developer**. That is the floor to connect: with `api` and the Developer role, the token can push branches and open merge requests, which is everything Promptless needs to deliver a documentation change. A token that cannot open merge requests — one that lacks `api`, or that sits below the Developer role — is refused when you connect, with an inline error in the connect modal. The refusal comes before any project is fetched or any webhook written, so nothing is persisted. | ||
|
|
||
| Give the token the **Maintainer** role for the clean path. Maintainer lets Promptless install the merge-request webhooks across the group's projects automatically, so merge requests and comment mentions start documentation work without any manual webhook setup. A Developer-role token with `api` still connects: Promptless records the webhook limitation and surfaces it on the connection's card on the Integrations page, and the connection keeps working on later refreshes. To close the gap, add the webhooks by hand in GitLab, or raise the token to Maintainer and use the **Automatic webhooks** control on the connection's card to install them across every accessible project. |
There was a problem hiding this comment.
The connection card's visible control is a CardDrawer with label "Automatic webhooks"; its button (onReinstall) calls reinstall_gitlab_webhooks, which rewrites the webhook on every project the connection can reach.
| - Send only the necessary information about changes to Promptless | ||
| - Can be customized to focus on specific events | ||
|
|
||
| Automatic webhook setup needs the Maintainer role. See [Token scope considerations](#token-scope-considerations) for your options when a connected token can't manage webhooks automatically. |
There was a problem hiding this comment.
can_manage_hooks requires the api scope and GITLAB_MAINTAINER_ACCESS_LEVEL (40), confirming automatic webhook setup needs the Maintainer role.
|
|
||
| * **Research breakdown now reads Knowledge Base inline and attributes delegated research:** Each trigger's research breakdown—on the Triggers page and a suggestion's **Triggers & Analysis** tab—now shows Knowledge Base reads inline, in the sequence the agent read them, instead of grouped at the end. Delegated research appears as an attributed branch labeled with the subagent type and its tool-call count. A "research agents" callout appears next to the summary when Promptless delegates research. See [Research breakdown](/docs/for-docs/work-the-queue/web-interface#research-breakdown). | ||
|
|
||
| * **GitLab connect validates your token up front:** Connecting a GitLab group now validates the group access token before completing the connection. A token that can open merge requests connects; one that can't—missing the `api` scope or below the Developer role—is refused in the connect modal with an inline error, before any project is fetched or saved, so you can correct the token on the spot. A Developer-role token with `api` connects and can publish and read context; because installing merge-request webhooks automatically needs the Maintainer role, that limitation is recorded and shown on the connection's card, where you can add the webhooks by hand or raise the token to Maintainer. See [GitLab integration](/docs/for-docs/reference/integrations/gitlab#token-scope-considerations). |
There was a problem hiding this comment.
Changelog summary of the connect preflight: refusal (400 with preflight.blocking_reason) precedes project enumeration and persistence; a Developer-role token with api connects and the webhook limitation is recorded (can_manage_hooks BLOCKED path, logged and skipped rather than attempted) and shown on the connection's card.
Corrects the GitLab integration docs for the merged behavior of Promptless/promptless #4848 + #4857: the api scope is the only hard connect requirement (group or personal access token), a target group path is required, Maintainer governs per-project webhook eligibility, and the connection card reports project counts by state. Updates the MR-trigger project selection, personal-token comment behavior, adjacent source-control and access-and-permissions pages, the folded changelog entry, and the gitlab-connect doc-detective spec.
| <Aside type="caution" title="Required Scope"> | ||
| The token must be a **group** access token with the **`api`** scope and the **Maintainer** role. Tokens without the `api` scope don't work with Promptless, and Maintainer is required because webhook creation is Maintainer-gated. GitLab has no read-only token option — see [Token scope considerations](#token-scope-considerations) for why. | ||
| <Aside type="caution" title="Required to connect"> | ||
| Connecting needs an access token with the **`api`** scope, plus the target group's path. Promptless verifies the scope inline at connect time, before fetching any project. The **Maintainer** role governs per-project webhook eligibility; see [Token scope considerations](#token-scope-considerations) for how a token's role shapes which projects get automatic webhooks. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx:42
Citation withdrawn.
connect_gitlab_installation resolves the group and computes token capability, then raises HTTP 400 via _gitlab_token_refusal (missing api scope) or gitlab_primary_group_identity (missing group_path) before gitlab_group_project_inventory (project fetch) or any persistence — confirms the scope+group-path check runs inline before fetching any project.
Source: devtools.py:399–438 · 26ba6b9
|
|
||
| Each connected group appears as its own card on the [Integrations](https://app.gopromptless.ai/integrations) page. Each card is titled `GitLab (gitlab.com)` for a gitlab.com connection, or `GitLab · <host>` for a self-hosted instance. Every card shows a `Host:` line (`gitlab.com` for a gitlab.com connection, or the self-hosted domain) and a `Group:` line with the connected group. The card lists the connected group's projects by full path (for example, `promptless-engineers/<repo>`), sorted alphabetically. | ||
|
|
||
| The card also reports project counts by state: how many projects are visible, webhook-eligible, active, ineligible, and failed. Each state means: |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx:53
Citation withdrawn.
gitlabWebhookPresentation builds the "{synced} of {eligible} project webhooks active" title and separately reports the ineligible (below-Maintainer) count, confirming the card's visible/eligible/active/ineligible/failed state framing.
| ### Token scope considerations | ||
|
|
||
| **GitLab has no read-only option.** Connecting a GitLab group always performs writes with the group access token: it creates the merge-request webhooks across the group's projects, and it also sets the Promptless bot avatar as an incidental additional write. Webhook creation is the hard blocker — a read-only (`read_api`) token cannot create those webhooks, so the integration delivers no merge-request triggers and is connected but inert. Unlike the [GitHub (read-only) app](/docs/for-docs/reference/integrations/github-read-only), GitLab has no read-only equivalent, so even a triggers-and-context-only setup needs a write-capable token. | ||
| The only hard requirement to connect is the **`api`** scope. The `api` scope is write-capable, so a token that has it can push branches, open merge requests, and read project content — everything Promptless needs to deliver a documentation change. Promptless checks for the scope inline when you connect, before it fetches or saves any project, so you can correct the token on the spot. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx:144
Citation withdrawn.
_gitlab_token_refusal only checks capability.can_open_merge_requests (the api scope); a group-level role never rejects the connection, confirming the api scope is the only hard connect requirement.
Source: devtools.py:378–396 · 26ba6b9
| A low group-level role still connects, because a token's direct project memberships can grant stronger access than its group role. Promptless evaluates access per project. | ||
|
|
||
| Promptless writes only to the projects you configure as doc collections. That's an application-level restriction Promptless enforces — the token itself doesn't impose it. | ||
| A group access token is a GitLab bot identity, so Promptless applies its bot avatar to the merge requests and comments it creates. A personal access token represents its human owner, and that owner's own `@promptless` merge-request comments can invoke Promptless. For a team or org-wide rollout, a group access token is org-owned and keeps working across staffing changes, while a personal access token stays tied to its owner's continued access. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx:148
Citation withdrawn.
gitlab_note_is_promptless_authored suppresses a note only via the loop-prevention marker, a matching recorded bot user, or (for a namespace token only) matching the source MR's author — a personal-token owner's own comments match none of these and are acted on.
| A low group-level role still connects, because a token's direct project memberships can grant stronger access than its group role. Promptless evaluates access per project. | ||
|
|
||
| Promptless writes only to the projects you configure as doc collections. That's an application-level restriction Promptless enforces — the token itself doesn't impose it. | ||
| A group access token is a GitLab bot identity, so Promptless applies its bot avatar to the merge requests and comments it creates. A personal access token represents its human owner, and that owner's own `@promptless` merge-request comments can invoke Promptless. For a team or org-wide rollout, a group access token is org-owned and keeps working across staffing changes, while a personal access token stays tied to its owner's continued access. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx:148
Citation withdrawn.
schedule_promptless_bot_avatar is called only when capability.token_type is GROUP_ACCESS_TOKEN, confirming the bot avatar is applied only for a group token; a personal token's owner keeps their own avatar.
Source: devtools.py:539–540 · 26ba6b9
| A group access token is a GitLab bot identity, so Promptless applies its bot avatar to the merge requests and comments it creates. A personal access token represents its human owner, and that owner's own `@promptless` merge-request comments can invoke Promptless. For a team or org-wide rollout, a group access token is org-owned and keeps working across staffing changes, while a personal access token stays tied to its owner's continued access. | ||
|
|
||
| Two layers limit what Promptless can reach. The first is a hard, token-level limit: if you scope the group access token to a group or subgroup that contains only your documentation projects, the token can't reach anything outside it. Scoping the token to a documentation-only subgroup is safe only when your trigger and context source projects and your docs-destination projects all live within that same group or subgroup — otherwise the token can't reach source projects outside it. The second is an application-level path scope on the doc collection, which limits which files Promptless can change. | ||
| The **Maintainer** role is a per-project webhook-eligibility condition. Promptless reads the full tree of visible projects along with a Maintainer-level inventory, then installs merge-request webhooks on the webhook-eligible projects — including the projects the token reaches through direct project membership. Projects below Maintainer stay visible for context and publishing, and you add a webhook for them by hand in GitLab. Adding a webhook by hand also requires the Maintainer role on that project, so if you don't have it, ask a project Maintainer or Owner. To install webhooks across the eligible projects at once, use the **Automatic webhooks** control on the connection's card. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx:150
Citation withdrawn.
gitlab_group_project_inventory reads the full visible project tree plus a min_access_level=40 (Maintainer) inventory via gitlab_group_projects, which evaluates effective per-project access including direct project membership, and marks each project's webhook_eligible flag.
Source: devtools.py:1514–1559 · 26ba6b9
|
|
||
| ## Project selection | ||
|
|
||
| Selection is pick-only: you choose from the GitLab projects that have a confirmed webhook. Each entry you list under `repos` is a webhook-enabled GitLab project. The **All webhook-enabled repositories** toggle covers every webhook-enabled GitLab project in one selection, and in YAML `repos: all` means the same thing. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/connect/triggers/gitlab-merge-requests.mdx:60
Citation withdrawn.
gitlabTriggerRepoInventoryFromConfig builds the picker only from projects present in each connection's webhook_sync.synced_project_paths, confirming pick-only selection from confirmed-webhook GitLab projects.
|
|
||
| ## Project selection | ||
|
|
||
| Selection is pick-only: you choose from the GitLab projects that have a confirmed webhook. Each entry you list under `repos` is a webhook-enabled GitLab project. The **All webhook-enabled repositories** toggle covers every webhook-enabled GitLab project in one selection, and in YAML `repos: all` means the same thing. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/connect/triggers/gitlab-merge-requests.mdx:60
Citation withdrawn.
MergeRequestFields sets allowFreeText={!requireConfirmedWebhooks} and allRepositoriesLabel to literal "All webhook-enabled repositories" when requireConfirmedWebhooks is true, confirming the toggle label and pick-only (no free text) behavior for GitLab MR triggers.
|
|
||
| Selection is pick-only: you choose from the GitLab projects that have a confirmed webhook. Each entry you list under `repos` is a webhook-enabled GitLab project. The **All webhook-enabled repositories** toggle covers every webhook-enabled GitLab project in one selection, and in YAML `repos: all` means the same thing. | ||
|
|
||
| A saved selection stays in your configuration even when its project is not active on the connection card, and Promptless flags it with a warning. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/connect/triggers/gitlab-merge-requests.mdx:62
Citation withdrawn.
unconfirmedGitlabTriggerRepos flags saved repos absent from the confirmed inventory, and RepoSelector renders a warning ("no longer have a confirmed Promptless webhook... configuration is unchanged") without removing them from the saved value.
|
|
||
| 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. | ||
|
|
||
| When you connect with a personal access token, your own `@promptless` comments on a merge request are acted on, so a mention you post yourself starts documentation work like any other. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/connect/triggers/gitlab-merge-requests.mdx:109
Citation withdrawn.
resolve_gitlab_bot_user returns None immediately for a PERSONAL_ACCESS_TOKEN (and clears any stale recorded bot user), so the personal-token owner's own comments are never matched as Promptless-authored and are dispatched normally.
|
|
||
| * **Research breakdown now reads Knowledge Base inline and attributes delegated research:** Each trigger's research breakdown—on the Triggers page and a suggestion's **Triggers & Analysis** tab—now shows Knowledge Base reads inline, in the sequence the agent read them, instead of grouped at the end. Delegated research appears as an attributed branch labeled with the subagent type and its tool-call count. A "research agents" callout appears next to the summary when Promptless delegates research. See [Research breakdown](/docs/for-docs/work-the-queue/web-interface#research-breakdown). | ||
|
|
||
| * **Connect GitLab with a group or personal access token:** You can now connect a GitLab group with a group access token or a personal access token that has the `api` scope. Supply the target group path, and Promptless verifies the scope inline as you connect. Promptless then installs merge-request webhooks on the projects where the token has Maintainer access and reports each project's state — visible, webhook-eligible, active, ineligible, and failed — on the connection's card. See [GitLab integration](/docs/for-docs/reference/integrations/gitlab#token-scope-considerations). |
There was a problem hiding this comment.
Citation
src/content/changelog/changelogs/august-2026.mdx:32
Citation withdrawn.
connect_gitlab_installation end to end: accepts group_access_token as either token type, requires group_path, refuses inline on missing api scope before persistence, installs webhooks only on Maintainer-eligible projects, and records per-project state — matches the changelog's summary of the shipped behavior.
Source: devtools.py:399–545 · 26ba6b9
| GitLab connects with a GitLab access token — a group access token or a personal access token — that carries the `api` scope, which is read-write. Publishing reuses that same token. For a team or org-wide rollout, a group access token is org-owned and keeps working across staffing changes, while a personal access token stays tied to its owner's continued access. | ||
|
|
||
| Connecting a GitLab group always writes with the token because it creates the merge-request webhooks and sets the bot avatar, so there's no read-only option: a trigger or context source needs the `api` scope with the **Maintainer** role (webhook management is Maintainer-gated), and a docs destination needs the `api` scope with at least the **Developer** role to push a branch and open a merge request. Promptless restricts those writes to the projects you configure as doc collections, but this is an application-level restriction Promptless enforces, not a limit imposed by the token itself. | ||
| The only hard requirement to connect is an access token with the `api` scope. A low group role still connects, because a token's direct project memberships can grant stronger access than its group role, so Promptless evaluates access per project. The **Maintainer** role is not a connection requirement — it governs per-project webhook eligibility. Promptless installs merge-request webhooks on the projects where the token has Maintainer access. Projects below Maintainer stay visible for context and publishing, and you add a webhook for them by hand in GitLab. Adding a webhook by hand also requires the Maintainer role on that project, so if you don't have it, ask a project Maintainer or Owner. Promptless writes only to the projects you configure as doc collections. That is an application-level restriction Promptless enforces. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/connect/source-control.mdx:62
Citation withdrawn.
_gitlab_token_refusal only rejects on a token-wide missing api scope (capability.can_open_merge_requests); a group-level role never rejects the connection, because GitLab roles are project-specific and a personal token's direct project membership can exceed its group role — confirms "only hard requirement is api scope" and "low group role still connects, Maintainer is not a connection requirement."
Source: devtools.py:378–396 · 26ba6b9
| GitLab connects with a GitLab access token — a group access token or a personal access token — that carries the `api` scope, which is read-write. Publishing reuses that same token. For a team or org-wide rollout, a group access token is org-owned and keeps working across staffing changes, while a personal access token stays tied to its owner's continued access. | ||
|
|
||
| Connecting a GitLab group always writes with the token because it creates the merge-request webhooks and sets the bot avatar, so there's no read-only option: a trigger or context source needs the `api` scope with the **Maintainer** role (webhook management is Maintainer-gated), and a docs destination needs the `api` scope with at least the **Developer** role to push a branch and open a merge request. Promptless restricts those writes to the projects you configure as doc collections, but this is an application-level restriction Promptless enforces, not a limit imposed by the token itself. | ||
| The only hard requirement to connect is an access token with the `api` scope. A low group role still connects, because a token's direct project memberships can grant stronger access than its group role, so Promptless evaluates access per project. The **Maintainer** role is not a connection requirement — it governs per-project webhook eligibility. Promptless installs merge-request webhooks on the projects where the token has Maintainer access. Projects below Maintainer stay visible for context and publishing, and you add a webhook for them by hand in GitLab. Adding a webhook by hand also requires the Maintainer role on that project, so if you don't have it, ask a project Maintainer or Owner. Promptless writes only to the projects you configure as doc collections. That is an application-level restriction Promptless enforces. |
There was a problem hiding this comment.
Citation
src/content/docs/docs/for-docs/connect/source-control.mdx:62
Citation withdrawn.
gitlab_group_project_inventory fetches the full visible-project tree plus a second min_access_level=40 (Maintainer) inventory and marks each visible project's webhook_eligible flag; connect_gitlab_installation installs webhooks only on eligible projects — confirms Maintainer governs per-project webhook eligibility (not connecting) and that below-Maintainer projects stay visible for context/publishing but need a manual webhook.
Source: devtools.py:1514–1559 · 26ba6b9
|
In reply to this discussion I started this change over from
The rewrite leaves out the changelog files, the Doc Detective test, the other pages, and the earlier page-wide wording cleanup. Review: https://app.gopromptless.ai/suggestions/4dcd4c73-c313-401f-b1e1-61412944d895 |
…nect-token-preflight-docs # Conflicts: # src/content/docs/docs/for-docs/connect/triggers/gitlab-merge-requests.mdx # src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx
|
I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed. |
…nect-token-preflight-docs
…nect-token-preflight-docs # Conflicts: # src/content/docs/docs/for-docs/connect/source-control.mdx # src/content/docs/docs/for-docs/connect/triggers/gitlab-merge-requests.mdx # src/content/docs/docs/for-docs/reference/integrations/gitlab.mdx
hawkeyexl
left a comment
hawkeyexl
left a comment
There was a problem hiding this comment.
I'm concerned about adding details about a personal access token. While they work, they're not officially supported. Remove mention of them.
|
In reply to this discussion I'll remove the mentions of personal access tokens from this suggestion, since they aren't officially supported. I'll reply here once the update is pushed. |
|
In reply to this discussion I removed every mention of personal access tokens, so these pages describe only group access tokens. That covers the token requirements table, the prerequisites, the connect steps, and the page metadata in The other corrections are unchanged: the One mismatch remains in the product: the dashboard's GitLab connect window still tells users to use "a group or personal access token" ( Review: https://app.gopromptless.ai/suggestions/4dcd4c73-c313-401f-b1e1-61412944d895 |
Open in Promptless
Requested by: Prithvi (source PR author, Promptless/promptless#4848)
The GitLab docs described the earlier connect requirements. This updates three pages and the shared GitLab connect partial to match how GitLab connections and merge request triggers work now. The token remains a group access token.
Rewritten from scratch at reviewer request (InlinePizza): the branch was reset to
main, and only the factual corrections were re-applied. The changelog files, the Doc Detective spec,gitlab-projects.mdx, andaccess-and-permissions.mdxmatchmain.Review feedback (Manny): personal access tokens work but aren't officially supported, so every mention of them was removed. The pages again describe only a group access token, including the token-type row, the Owner-role prerequisite, the connect steps, and the frontmatter description, keywords, and intent. The note about which GitLab identity posts merge requests was removed with it.
Changes:
reference/integrations/gitlab.mdxandsrc/partials/integrations/gitlab-connect.mdx: the group access token needs theapiscope. Promptless checks the scope when you connect and rejects a token without it. A low group role still connects, and the Maintainer role decides which projects get merge-request webhooks. Also points Repository access at the verified-project picker and replaces two stale troubleshooting rows (read_apiand Developer role).connect/triggers/gitlab-merge-requests.mdx: triggers fire on open and merge, not updates (Promptless/promptless#5281). New short "Trigger events" and "Project selection" subsections (verified-webhook picker, "All webhook-enabled repositories", "Webhook verification pending" with "Check now"). The webhook delivery status box counts any webhook from the trigger's projects (#5249).connect/source-control.mdx: connecting needs only theapiscope. Trigger source projects need Maintainer for webhooks, and publishing needs Developer.No changelog entry is included.
Review feedback (InlinePizza, 2026-10-02): "start over writing this docs change from scratch." Applied as asked: the branch was reset to
mainwith a new commit (no force-push), and the PR went from 7 files (+200/−199) to 3 files (+46/−31). Earlier review point still holds: no September changelog entry. Branch citations were withdrawn and re-added at the new lines.Trigger Events
Validation: Vale (collection + canonical/KB) found 0 new findings. remark-lint passes on the changed files.
npx manni meta validatepasses (131 files).