Source: https://docs.pageloop.ai/guides/gitlab-integration

# GitLab integration

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

> [!NOTE]
>
> 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 `api` scope. 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.

> [!WARNING]
>
> 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

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

   ![Knowledge base section of Integrations with the GitLab card's Connect button outlined](/images/uploads/uploaded-image-0-2483622b.png)

2. In **Connect GitLab**, keep `https://gitlab.com` as the **GitLab instance URL**, or enter your self-managed instance's base address. Paste your token into **Access token** and select **Continue**.

   ![Connect GitLab dialog with GitLab instance URL, a masked access token, and Continue outlined](/images/uploads/uploaded-image-1-9ac41422.png)

3. Pageloop checks the token. If an amber note says the token lacks the `api` scope, create a token with that scope.

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

   ![Connect GitLab dialog showing the connected user, knowledge base project, and product project selection](/images/uploads/uploaded-image-2-df3cdb39.png)

   ![Product projects picker open with two projects ticked](/images/uploads/uploaded-image-3-1330e4f3.png)

5. 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**.

   ![GitLab card reading Connected with the Configure GitLab gear outlined](/images/uploads/uploaded-image-4-0b63eb1d.png)

### 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:

1. In GitLab, open the project's **Settings → Webhooks → Add new webhook**.
2. Copy the **Payload URL** and **Signing token** from Pageloop into GitLab. The signing token has **Show**, **Copy**, and **Regenerate** controls.
3. Tick the triggers listed for that project in Pageloop and add the webhook.
4. 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. |

> [!WARNING]
>
> 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](/guides/connect-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](/guides/workflows) to configure the workflow.

Optional merge request checks live in **Settings → Knowledge base**. See [Check documentation pull requests](/guides/pull-request-checks) for setup and behavior.

## Disconnect GitLab

1. Point at **Connected** on the GitLab card; it changes to **Disconnect**. Select it.
2. Review **Disconnect GitLab?**.
3. Select **Disconnect** to confirm, or **Keep connected** to cancel.

![Disconnect GitLab? dialog with Keep connected and Disconnect controls](/images/uploads/uploaded-image-5-4fd7bf14.png)

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

## Related guides

- [GitHub integration](/guides/github-integration)
- [Check documentation pull requests](/guides/pull-request-checks)
- [Workflows](/guides/workflows)
- [Connect your knowledge base](/guides/connect-knowledge-base)
- [Troubleshooting](/guides/troubleshooting)
