Integrations
GitLab integration
Connect GitLab with an access token, choose documentation and product projects, and manage webhooks and access.
GitLab integration
Connect GitLab to give Pageloop a project for your documentation and product projects to watch for changes. One connection holds one Knowledge base project, where your docs live, and any number of Product projects, whose code and issues Pageloop reads to suggest documentation updates.
Pageloop connects with an access token and your GitLab instance URL. There is no sign-in redirect. The token's identity and project memberships determine what Pageloop can reach.
GitLab.com is fully supported. A self-managed GitLab instance can connect using its public HTTPS address, but Pageloop does not yet read code and issues from self-managed projects. The instance must be reachable from the public internet.
Before you begin
- Sign in to Pageloop as an Admin. Editors and Contributors see Integrations read-only.
- In GitLab, create a token with the
apiscope. Make sure the token's identity has the Maintainer role on each project Pageloop should watch or write to, so Pageloop can create webhooks. - Decide which project holds your docs and which product projects Pageloop should watch. A project cannot be both.
Use a GitLab service account at the top-level group, added as a member of only the projects Pageloop should reach. Personal, project, group, and fine-grained tokens are also accepted. The Find your service account token link in the connection dialog opens GitLab's service account documentation.
A token with a read-only scope can connect, but it cannot register webhooks or reply on issues. Use the api scope for the integration.
Connect and configure GitLab
-
Open Integrations from the sidebar, or Settings → Workspace → Integrations. Find GitLab under Knowledge base and select Connect. GitLab also appears under Project management; both cards represent one connection.
-
In Connect GitLab, keep
https://gitlab.comas the GitLab instance URL, or enter your self-managed instance's base address. Paste your token into Access token and select Continue. -
Pageloop checks the token. If an amber note says the token lacks the
apiscope, create a token with that scope. -
Choose your projects:
- Knowledge base project: choose
<your docs project>. - Product projects: tick the projects Pageloop should watch. The picker describes these as “Watched for labeled issues and mentions.” A project cannot be both the knowledge base and a product project.
The dialog shows Connected as @<username>, identifying the GitLab user behind the token. Your team can mention that handle, such as
@<your service account>, on an issue to ask Pageloop for a documentation update. Pageloop replies on the issue. - Knowledge base project: choose
-
Select Connect. The GitLab connected toast confirms the connection, and the card reads Connected with a gear button. If GitLab refuses a webhook, the dialog opens the manual webhook steps instead. Add each webhook in GitLab as described below, then select Done.
Change settings later
Select the gear (Configure GitLab) to change your projects, then select Save Configuration. If a project still needs a webhook added by hand, the dialog shows a message such as “1 project still needs its webhook added in GitLab.” Select View setup to open the instructions.
To replace an expired or revoked token, disconnect GitLab, then connect again with a fresh token and choose your projects again. To switch to a different GitLab instance, disconnect first.
Webhooks
When you save, Pageloop creates a webhook in each chosen project with SSL verification on:
| Project type | Webhook events |
|---|---|
| Knowledge base project | Push events, comments, and merge request events. |
| Product projects | Comments and merge request events. |
If GitLab refuses to create a webhook, usually because the token's role on that project is below Maintainer, Pageloop shows the details for manual setup:
- In GitLab, open the project's Settings → Webhooks → Add new webhook.
- Copy the Payload URL and Signing token from Pageloop into GitLab. The signing token has Show, Copy, and Regenerate controls.
- Tick the triggers listed for that project in Pageloop and add the webhook.
- Repeat for each project that needs manual setup, then select Done in Pageloop.
Each project shows one of these delivery statuses:
| Status | Meaning |
|---|---|
| No deliveries yet | Pageloop has not received a delivery for the project. |
| Verified | Webhook deliveries verify successfully. |
| Deliveries arriving but not verifying | The signing token in GitLab does not match the token in Pageloop. |
Regenerating a signing token breaks that webhook until you paste the regenerated token into GitLab. Update the webhook in GitLab after using Regenerate.
Integration roles
GitLab can hold the Knowledge base role, but not the Ticketing role. Connecting GitLab does not assign a role automatically. In a workspace with a Pageloop-hosted knowledge base, the Knowledge base role shows Pageloop Docs; GitLab is the repository behind it. See Connect your knowledge base.
Permissions and what Pageloop can read and write
| Project type | Access | What Pageloop does |
|---|---|---|
| Knowledge base project | Read and write | Pushes to the published branch and merged merge requests sync your docs into Pageloop. Pageloop commits documentation edits to a branch and opens a merge request for review. |
| Product projects | Read access to merge requests, code files, and issues | Reads product changes to draft documentation updates. Pageloop never changes product code and never reads confidential issues. It can reply on issues when your team mentions the connected GitLab user. |
Draft updates from merged merge requests
A workflow with the trigger When a merge request is merged can start a run when a merge request merges into a selected product project's default branch. The run drafts documentation updates for review. See Workflows to configure the workflow.
Optional merge request checks live in Settings → Knowledge base. See Check documentation pull requests for setup and behavior.
Disconnect GitLab
- Point at Connected on the GitLab card; it changes to Disconnect. Select it.
- Review Disconnect GitLab?.
- Select Disconnect to confirm, or Keep connected to cancel.
Pageloop stops reading from and writing to GitLab and removes the webhooks it created. Webhooks you added by hand stay in GitLab; delete them there. Disconnecting does not revoke the token in GitLab. Revoke the token there if you no longer need it.
If setup was closed before projects were saved, the card shows Needs reconnecting. Open the ... menu, select Disconnect, then select Connect again.
Troubleshooting
In the messages below, <project> and <old URL> stand for the values shown by Pageloop.
| Message or symptom | What to check |
|---|---|
| “Instance URL must be a public https:// GitLab address” | Use the instance's public HTTPS base address. |
| “GitLab rejected the token. Check the token and instance URL, then try again.” | Check that the token and instance URL are correct, then try again. |
| “This GitLab token has expired. Create a new one with the api scope, then try again.” | Create a token with the api scope and try again. |
| “GitLab refused the request (403). The token itself was accepted, so this is an account or permissions problem rather than a bad token.” | Read GitLab's reason following the message, such as an unconfirmed email or a blocked user, and resolve that account or permissions problem. |
| “Couldn't reach a GitLab API at that URL — check the instance URL.” | Use the base address, such as https://gitlab.com or https://your-host/gitlab for a relative-URL install, not a group or project page. |
| “Couldn't reach that GitLab instance — the request timed out or the host didn't answer.” | Check the URL and that the instance is reachable from the public internet. |
| “GitLab returned an error while checking the connection. This is usually temporary — wait a moment and try again.” | Wait a moment and try again. |
| “No GitLab projects are visible to this token. Check the token identity's project memberships.” | Check that the token's identity is a member of the intended projects. |
| “GitLab authentication failed. Please reconnect your GitLab integration.” | The token was revoked or expired. Disconnect, then connect with a fresh token and choose your projects again. |
“The connected GitLab token cannot read <project>. Check its access, then try again.” | Check the token's access to the named project, then try again. |
| “A project cannot be both the knowledge base and a product repo.” | Choose different projects for the knowledge base and product projects. |
| Deliveries arriving but not verifying | Compare the signing token in GitLab with Pageloop's token, or select Regenerate and paste the regenerated token into GitLab. |
“This organization's GitLab connection is configured against <old URL>…” | Disconnect GitLab first, then connect to the other instance. |
| “Could not disconnect GitLab” | Try again in a moment. |

