Source: https://docs.pageloop.ai/guides/change-sets

# Change Sets

# Change sets

A change set is a batch of Knowledge Base edits that you review and publish together through a Git branch and pull request. Use a change set when several page edits, images, navigation changes, or site settings belong to the same update. Keeping related edits together lets you review the complete result before it reaches readers.

> [!NOTE]
>
> This workflow applies to a repository-backed Pageloop docs site. You need permission to edit the Knowledge Base and permission to publish or merge for those actions. Connected help centers can have different publishing controls. On GitLab, repository review uses a merge request rather than a pull request.

## How edits are grouped

A change set is a workspace for one proposal, not just the page you have open.

- **Pageloop proposals:** Open the proposal in **Inbox** to review its changes across the affected pages. Review agent-generated proposals there rather than looking for an editable branch in the Knowledge Base workspace selector.
- **Direct edits:** In **Knowledge Base**, open **Switch workspace** above the tree and choose **New branch…**. Enter a **Branch name** and click **Create branch**. Edits you make in that workspace belong to that change set. Switch to another change set to keep a separate update apart.
- **Existing Main drafts:** **Preview your unpublished changes** opens **Preview these changes**. Choose the pages, **Navigation**, and **Site settings** that belong together, check the branch name, then continue with **Create pull request**. This moves the selected drafts into a change set; it is not just a preview of Main. Navigation needed for a new page travels with that page.

![The Knowledge Base workspace selector with Main and New branch](/images/uploads/screenshot-5fe5edb7.png)

In an editable change set, the publish panel lists everything the push carries. Unlike Main's publish panel, the change set does not offer per-item selection at push time. Keep unrelated edits in separate workspaces rather than assuming you can exclude them when you push.

## Review and publish a change set

### Review a Pageloop proposal in Inbox

1. Open the proposal in **Inbox**. Use **Changes** to review the suggested edits and select a page in the tree to read the **Article** with its changes in context.
2. Record the decisions you intend to publish. Check all affected pages, not only the first page. Resolve any drift banners or changes that still need a decision.
3. Check the publish menu's selected items and accepted changes. Use **Raise PR** to open the repository proposal, or **Update PR** to send further reviewed changes to the existing pull request. A review-backed publish panel can instead label this action **Publish accepted review**; that action excludes pending and rejected changes.
4. Open the resulting pull request. Review the actual repository diff and required checks before merging.

Raising or updating a pull request does not make the changes live.

### Publish direct Knowledge Base edits

1. Select the change set in **Switch workspace**. Check that the editor has saved your latest edits.
2. Use **Show differences** to compare a page's draft with its published content. Review **Page details** as well as the body: a title, description, or slug can change without a body edit.
3. Use **Generate preview**, then **Open preview**, to inspect the unpublished site. After further edits, use **Preview options → Rebuild** before checking the result again.
4. Open **Publish**. Check the **Branch**, changed pages, **Navigation**, and **Site settings**. Click **Push to branch** to open or update the pull request.
5. Review and merge the pull request in the repository. Where Pageloop offers **Merge**, it opens a separate **Merge change set** confirmation. **Push & merge** pushes pending edits first, then asks you to confirm with **Merge now**.

The live site updates after the merge syncs back. If the repository refuses a merge because of conflicts, required checks, branch protection, or unresolved discussions, resolve the stated issue in the repository before trying again.

## How change sets relate to Git

The connected repository holds your documentation files. **Main** represents the site's tracked branch; that branch is not necessarily named `main` in Git. A change set keeps a proposed update separate from that published baseline.

Saving in the editor stores an unpublished draft. Pushing writes the proposal to its branch and opens or updates its pull request. Merging brings the reviewed proposal into the tracked branch, after which the site syncs the merged content. A preview is a temporary site, not evidence that a merge or live publication has happened.

Repository edits also matter. Someone can change the tracked branch while you review a draft, or push commits to a proposal branch. Before replacing repository work, read any warning that names overwritten files or commits Pageloop did not write. Do not use **Push anyway** or **Publish anyway** merely to clear a warning.

### Why Pageloop does not merge on its own

Drafting, accepting changes, generating a preview, and opening a pull request are separate from authorizing a merge. Pageloop prepares the proposal; you decide whether the complete update should reach readers. This keeps editorial approval and the repository's review requirements in your team's control.

Pageloop can execute an explicitly authorized merge, but it does not treat an AI-generated draft or a successful push as permission to merge. The **Merge now** confirmation is a deliberate release decision, not an automatic next step after review.

## Troubleshooting: Main changed under the draft

Drift means the draft was based on an earlier published version and the relevant content has changed since. A teammate may have edited, moved, or deleted a page, merged another change set, changed navigation, or created a page at an address your draft uses. Drift does not necessarily mean the edits conflict: changes in different passages may still fit together.

### See what changed

In **Inbox**, read the banner's page name, published version, and attribution. The banner can say **Out of date.**, **Article moved.**, **Article deleted.**, **Address taken.**, or **Navigation changed.**

Use **Read the … version** to open the published page in Knowledge Base with a way back to the proposal. Where the version is linked, open it to inspect the repository commit. Compare the published content with the proposed change before deciding what to keep. Banners appear across affected pages in **Changes** and **Activity**; the **Article** tab shows the banner for the page you are reading.

### Resolve drift in an Inbox proposal

| What changed                                | What to do                                                                                                                                                                                                                                     |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page text changed                           | Click **Update my changes** to apply the proposal to the newer published version. Review the resulting tally: changes can be kept, already published, need your decision, or no longer have a place in the article. Updating does not publish. |
| Page moved                                  | Use **Use new location**. If the page was also edited, review the updated text and any remaining decisions.                                                                                                                                    |
| Page was deleted                            | Choose **Recreate article** to include it again on publication, or reject the affected changes to leave it deleted. Check changes that link to the deleted article too.                                                                        |
| A new page's address is taken               | Choose another address with **Publish ours at …**, or **Keep theirs** to leave the published page in place and exclude your new article.                                                                                                       |
| Navigation changed                          | Review the affected navigation changes against the published structure. Do not assume the old destination still exists.                                                                                                                        |
| The version the draft used no longer exists | Use **Run again** to redraft against the published version. The confirmation warns that every decision returns to undecided.                                                                                                                   |

![Missing-version warning with Run again](/images/uploads/screenshot-58ac43ec.png)

After an update, inspect **Choose a version** and **Text removed** cards. Where available, compare **Original**, **Published now**, and **Pageloop’s change**. A successful update does not mean every change is ready to publish. If Main changes again, read the newer version and update again. If Pageloop is still drafting or refining, wait for the run to finish before resolving drift.

### Resolve a direct Knowledge Base draft

The editor's drift banner uses different controls:

- **Bring in the GitHub changes** preserves your draft and incorporates upstream edits. If both sides changed the same sections or page settings, choose **Use GitHub's** or **Keep mine** for each conflict, then click **Bring in changes**. If a safe line-by-line merge is not possible, choose a whole-page version instead.
- **Take the GitHub version** drops your draft in favor of the upstream version. The confirmation warns that dropping the draft cannot be undone. In an already-pushed change set, the branch matches that choice after the next publish.
- For an upstream deletion, **Revert delete** restores the draft as a new page to publish; **Sync delete** drops your draft and leaves the page deleted.
- For an address collision, **Keep mine at another address** preserves your page at another path. A restore can also ask for a different address if the original path is taken.

A banner saying the page changed on the branch means someone pushed to that pull request's branch, rather than only changing Main. Review that branch's changes before choosing a resolution.

### If the resolved draft still looks wrong

Before pushing or merging, check:

1. **The workspace and page:** Confirm that you are reading the intended change set, docs version, and page address, especially after a move or restore. Return from the published-page view to the proposal before continuing review.
2. **Save and refresh state:** Resolve save errors first. If someone else updated the review or resolved drift while you were choosing, reload the review and inspect the resulting content rather than applying an old choice again.
3. **Remaining decisions and page details:** Review unresolved cards, removed text, and title or description conflicts separately. A clean body update does not settle every metadata decision.
4. **Content and navigation:** Re-read the full article, links, code blocks, and MDX in **Markdown source** where needed. Check that moved or recreated pages appear in the intended navigation and that destinations still exist.
5. **Preview and repository state:** Rebuild the preview after edits. Check sync warnings for incomplete content. Compare the pull request diff with the reviewed draft; if decisions changed after the PR was created, update the PR before merging. A stale preview or a site still syncing can differ from the draft without losing your saved work.

If publication says the latest repository docs do not sync, fix the reported repository problem before publishing again. Do not override a drift warning to compensate for a draft that you have not verified.

## Related

- [The Pageloop sidebar](/guides/pageloop-sidebar)
- [Writing docs](/guides/writing-docs)
