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

# GitHub integration

# GitHub integration

Connect GitHub to give Pageloop a repository for your documentation and product code to watch for changes. One connection holds one **Knowledge base repository**, where your docs live, and any number of **Product repositories**, which Pageloop reads to suggest documentation updates.

Pageloop connects through the **Pageloop GitHub App**, installed on a GitHub account or organization. You do not enter a token or password.

## Before you begin

- Sign in to Pageloop as an **Admin**. Editors and Contributors see Integrations read-only, with the message “Your connected tools. An Admin can change their configuration.”
- Use a GitHub account allowed to install apps on the chosen account or organization. For an organization, this is usually an owner.
- Decide which repository holds your docs and which product repositories Pageloop should watch. If you do not have a docs repository, create an empty one on GitHub first.

## Connect and configure GitHub

1. Open **Integrations** from the sidebar, or **Settings → Workspace → Integrations**. Search for GitHub and select **Connect**. The card appears under both **Knowledge base** and **Code repository**, but both cards represent one connection.

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

2. On GitHub's Pageloop app installation page, choose the account or organization. Choose **All repositories** or **Only select repositories**, then install the app.

3. GitHub returns you to Pageloop. A **Connecting GitHub** page appears briefly, followed by **GitHub connected**. The GitHub settings dialog opens.

4. Review the settings:

   - **Installed on** shows the GitHub account. Use **Manage on GitHub** to grant more repositories; they appear when you return.
   - **Knowledge base repository:** choose `<your docs repository>`, or **None**. Pageloop publishes to this repository and opens pull requests for review.
   - **Product repositories:** select any number of repositories to watch for merged pull requests. The repository chosen as your knowledge base is not offered here.
   - **Installation health:** check for **Installed and reachable**. The dialog also shows when Pageloop last received a GitHub event, such as **Last event received 5m ago**, or **No events received yet**.

   ![GitHub settings with the installed account, knowledge base repository, two product repositories, installation health, and Save outlined](/images/uploads/uploaded-image-1-ec677f40.png)

   ![Product repositories picker open with two repositories ticked](/images/uploads/uploaded-image-2-877474cb.png)

5. Select **Save**. The **GitHub configured** toast confirms the change. If you set a knowledge base repository, the toast directs you to **Settings → Knowledge base** to sync it. Continue with [Connect your knowledge base](/guides/connect-knowledge-base).

6. If you added product repositories GitHub has not confirmed for you, Pageloop sends you to GitHub to authorize access. After authorization, **GitHub access verified** confirms: “Pageloop can now read your code repositories.”

7. Check that the GitHub card reads **Connected**. Select its gear button (**Configure**) to reopen the settings dialog.

![GitHub card reading Connected with the Configure gear outlined](/images/uploads/uploaded-image-3-d0eda8b7.png)

### Change settings later

Select the gear on the GitHub card. Repositories granted on GitHub appear when the dialog reopens. **Save** is enabled only after you change something.

### Integration roles

GitHub can hold the **Knowledge base** role, but never the **Ticketing** role. Connecting GitHub does not assign a role automatically. In a workspace with a Pageloop-hosted knowledge base, the Knowledge base role shows **Pageloop Docs**; GitHub is the repository behind it.

## Permissions and what Pageloop can read and write

| Repository type           | Access         | What Pageloop does                                                                                                                                                                                               |
| ------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Knowledge base repository | Read and write | Commits documentation edits to a branch and opens a pull request for review. Pushes to the published branch sync into Pageloop through GitHub App events; you do not need to create a webhook by hand.           |
| Product repositories      | Read only      | Reads a merged pull request's title, description, changed files, and diff, plus the repository's code files. Nothing is written to product repositories, and the agent never reads files that look like secrets. |

> [!NOTE]
>
> Pageloop reads a product repository's code only after GitHub confirms that a Pageloop Admin can see that repository. This usually happens during app installation. If confirmation is missing, the settings dialog shows **Verify GitHub access**.

### Draft updates from merged pull requests

A workflow with the trigger **When a pull request is merged** can start a run when a pull request merges into a selected product repository's default branch. The run drafts documentation updates for review. Pull requests opened by Pageloop itself and by dependency bots are skipped. See [Workflows](/guides/workflows) to configure the workflow.

For optional pull request checks on a Pageloop-hosted knowledge base, use **Settings → Knowledge base → Pull request checks**. See [Check documentation pull requests](/guides/pull-request-checks) for setup and behavior.

## Disconnect GitHub

1. Point at **Connected** on the GitHub card; it changes to **Disconnect**. Select it.
2. Review **Disconnect GitHub?**. The dialog explains that “Pageloop stops reading from and writing to it” and says whether GitHub held an integration role.
3. Select **Disconnect** to confirm, or **Keep connected** to cancel.

![Disconnect GitHub? dialog with Disconnect outlined](/images/uploads/uploaded-image-4-0b82a33f.png)

The **GitHub disconnected** toast says “The GitHub App is still installed on your account” and includes **Uninstall on GitHub**. Pageloop keeps your repository choices; connecting again on the same GitHub account restores them.

If you need a different set of repositories after disconnecting and they do not appear in GitHub's repository list, use **Uninstall on GitHub** to uninstall the Pageloop app, then select **Connect** again.

## Troubleshooting

In the messages below, `<repository>` and `<repositories>` stand for the repository names shown by Pageloop.

| Message or symptom                                                                                                                             | What to check                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| “No repositories granted. Grant at least one on GitHub.”                                                                                       | Select **Manage on GitHub**, grant repositories, then select **Retry**.                                                                   |
| “GitHub no longer authorizes this installation. Reinstall the Pageloop app on GitHub.”                                                         | The installation was removed, suspended, or moved. Reinstall the app on GitHub, then reopen the dialog.                                   |
| “Could not load repositories. Try again.”                                                                                                      | A temporary problem prevented loading. Select **Retry**.                                                                                  |
| “GitHub no longer grants: `<repositories>`. Remove them or grant them on GitHub.”                                                              | Untick the repositories or grant them on GitHub.                                                                                          |
| “Could not save. Try again.”                                                                                                                   | Try saving again.                                                                                                                         |
| Installation health shows **Suspended on GitHub** or **Not found on GitHub. Reinstall the Pageloop app.**                                      | Unsuspend or reinstall the app on GitHub.                                                                                                 |
| “Pageloop can no longer read `<repository>`”                                                                                                   | The knowledge base repository is no longer granted. Grant it again on GitHub.                                                             |
| “Configured but no longer granted: `<repositories>`”                                                                                           | Grant the repositories again on GitHub or remove them from the configuration.                                                             |
| “The docs agent can't read code from `<repositories>` until GitHub confirms your access.”                                                      | Select **Verify GitHub access** and authorize with a GitHub account that can see those repositories.                                      |
| “Some repositories are still unconfirmed”                                                                                                      | Check that each repository is granted to the Pageloop app, then verify with an account that can see it.                                   |
| **GitHub access not verified**, with “The GitHub authorization was cancelled.” or “Start Verify GitHub access from Pageloop, in the same tab.” | Start **Verify GitHub access** from Pageloop in the same tab and complete authorization.                                                  |
| **Error connecting GitHub**, with “State parameter mismatch” or “This GitHub installation cannot be connected by your GitHub account”          | A state mismatch means the installation finished in another browser or tab session. Start again from **Connect** in the same browser tab. |
| GitHub shows the app's Configure page and does not send you back.                                                                              | Change or save the repository access on GitHub to return to Pageloop.                                                                     |
| “Could not disconnect GitHub”                                                                                                                  | Try again in a moment.                                                                                                                    |

## Related guides

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