Automation

Check documentation pull requests

Enable pull request checks, understand failures and warnings, and ask Pageloop to prepare a fix for review.

Check documentation pull requests

Use pull request checks to catch documentation problems before merging changes to your published branches. Pageloop checks GitHub pull requests and GitLab merge requests in your connected docs repository and reports problems introduced by the proposed changes.

Admins enable the check and manage the connection. Developers can read the results, push corrections, or request a Pageloop fix from the pull request.

You need a Pageloop-hosted knowledge base connected to a repository. This feature is available when Knowledge base settings shows Pull request checks. Developer describes your work in the repository, not a Pageloop workspace role.

Turn on pull request checks

  1. As an Admin, open the Account menu in the top bar and select Settings.
  2. Under Workspace, select Knowledge base.
  3. In Source, turn on Pull request checks. The setting saves automatically.

The setting applies to subsequent pull request or merge request events targeting your published branches, including new commits. Turning it off stops subsequent checks and fix requests; fixes already waiting for review remain available.

Connection permissions

For GitHub, the Pageloop GitHub App needs access to the docs repository. Its Contents and Pull requests write permissions support repository changes and reviews. Approve the App's Checks and Issues permissions for the check, fix button, and @pageloop requests in your GitHub settings under Installed GitHub Apps. Use an account authorized to approve permission updates for the installation.

For GitLab, the connected account needs a token with the api scope and project permissions to read the repository, post merge request notes and commit statuses, and write fix branches and merge requests. Read-only token scopes are not sufficient. The project's webhook must deliver merge request and comment events to Pageloop.

Enabling the check does not by itself make a failed result prevent merging:

  • GitHub: mark Pageloop docs as a required check in your repository's branch protection or rules. Without Checks permission, Pageloop can comment and request changes, but cannot provide the required check.
  • GitLab: Pageloop posts the commit status pageloop/docs-check. Do not assume a failed status blocks merging; verify your project's merge requirements.

Read the result and act on it

Pageloop keeps a comment on the pull request, or a note on the merge request, and updates it as the checked commit changes. The comment identifies the checked commit, gives the result, and lists the problems introduced by the request. Expand the findings to see file paths and line numbers where available.

Only changes that would stop the site from publishing fail the check. Broken links and pages that do not render correctly appear as warnings, not failures.

ResultMeaningWhat to do
Docs check failedA change would prevent the docs site from updating, such as invalid docs.json or a navigation entry pointing to a missing page.Fix the listed Must fix before merging problems on the request's branch, or ask Pageloop to fix them. Push the correction and check the result for the latest commit before merging.
Docs check passed with warningsThe site can publish, but the listed problems will reach readers.Review Won’t block the merge, but will reach readers. Correct broken links or pages yourself, or ask Pageloop for a fix. A passing check does not mean the warnings are resolved.
Docs check passed without warningsPageloop found no problems introduced by the request.Continue your normal review and merge process.
Pageloop docs check couldn’t runPageloop did not complete validation. This is not a clean result.Read the explanation in the comment. Resolve the reported obstacle and push a new commit to run the check again.

Ask Pageloop to fix the findings

You can request a fix for failures or warnings after the latest commit's check finishes.

Automatic fixes are unavailable for public repositories and branches in forks. For a branch owned by Pageloop, use its existing Inbox item instead. The check results still help you correct the files yourself.

Use Fix with Pageloop

  1. Select Fix with Pageloop in the latest Pageloop comment on the pull request or merge request.
  2. Sign in to Pageloop as a member of the workspace that owns the site.
  3. Review the repository, commit, and findings on the fix page. Findings are labeled Must fix or Warning.
  4. Select Start fix. Opening the comment link alone does not start a fix.

Pageloop prepares the correction and sends it to your Inbox for review, assigned to you. The fix usually takes a few minutes. Use Review in Pageloop to open an available fix, or Open your inbox while waiting for the item. On GitHub, Back to the pull request returns you to the original request.

GitHub also offers Fix with Pageloop on the check itself when the App has Checks permission.

Comment @pageloop

Anyone who can comment on the pull request or merge request can ask for a fix, even without a Pageloop workspace account. Add a comment such as:

@pageloop fix

Pageloop starts from the latest checked commit and updates its comment with the fix's progress and a Review in Pageloop link. A request made from GitHub or GitLab is initially assigned to the Admin who connected the integration, or another Admin if needed. An Admin or Editor can open the Inbox item to take over the review while it remains assigned to that fallback Admin.

If Pageloop is already fixing the commit, use the existing review link rather than starting another fix. If the check is still running, wait for it to finish and ask again.

Review and return the fix to the request

  1. Follow Review in Pageloop or open the fix in Inbox. You need workspace access to review the fix; being able to comment on GitHub or GitLab does not grant that access.
  2. Review the proposed changes and resolve any questions before approving the fix. An Admin or Editor must approve delivery; Contributors cannot publish the fix.
  3. Return to GitHub or GitLab and finish the repository review:
    • GitHub: after approval, Pageloop adds the fix as commits on the original pull request's branch. Pull those commits before pushing more changes.
    • GitLab: after approval, Pageloop opens a merge request containing the fix into the original merge request's source branch. Review and merge that fix request to update the original request.
  4. Check the result for the updated commit before merging the original request into the published branch.

Nothing reaches the original request's branch until the fix has been reviewed and approved. Approving a fix does not merge the original request or publish the site.

If the branch advances after Pageloop prepares a fix, Pageloop may mark the fix as outdated instead of applying it. Ask again on the latest commit. If Pageloop cannot prepare a fix, use the comment's retry action or correct the files yourself.