Page Branching can be configured at two levels: globally for the whole site and per space. Site administrators set the site-wide default, and space administrators decide how branching behaves inside their own space.
Global administration
Site administrators can open Page Branching global settings (from Settings → Apps → Page Branching, or the app’s global settings entry) to decide whether Page Branching is enabled by default in all spaces.
If you turn this off, Page Branching is only available in spaces where a space administrator explicitly enables it – ideal for a controlled rollout.
Space administration
In each space, open Space settings → Apps → Page Branching to configure:
-
Enable Page Branching in this space – turn branching on or off for the space
-
Limit branches per page – cap how many active branches a page can have
-
Show a hint when someone edits a page that has open branches – recommend working in an existing branch instead of editing the page directly
-
After merge – choose whether merged branches are archived (moved to an archive area under Branches) or deleted
-
Merges require approval – require an approval before a branch can be merged, either by anyone who hasn’t edited the branch or by named approvers
We have found that Archive meets the needs of the majority of teams: it keeps a history of what was merged, which is great for audits and rollbacks. Pick Delete if you prefer a minimal page tree.
Merge approval
Teams working under review or compliance requirements often need a documented four-eyes check before a change reaches a live page. Turn on Merges require approval, and no branch in that space can be merged into its original page until it has been approved.
The setting is off by default. Once it is on, it applies to every merge of a branch into its original page in that space. Updating a branch from its original page is not affected.
Choose who can approve
While the setting is on, Who can approve offers two rules:
-
Everyone who hasn’t edited the branch can approve – no approver list is needed. Page Branching reads the branch page’s version history, and anyone who can open the branch and did not edit it may approve it. Whoever submits the branch picks who to notify.
-
Only named approvers can approve – only the people on the Approvers list may approve.
Your choice is saved as soon as you pick a rule. A space that turns on approval for the first time starts with Everyone who hasn’t edited the branch can approve. Spaces that already used merge approval before version 3.1.0 keep Only named approvers can approve and their approver list, so nothing changes for them until a space administrator switches.
Under Everyone who hasn’t edited the branch can approve, everyone who published a version of the branch page counts as having edited it, including the person who created the branch and anyone who co-edited a version. Pressing Update publishes a new version of the branch in your name, so it counts too, and so does writing a merge resolution page for the branch. If the branch’s edit history can’t be read, nobody can approve the branch until it can.
Name the approvers
With Only named approvers can approve, an Approvers list appears below the rule. Search Confluence users by name and click Add, and use Remove to take someone off the list again. A space can have up to 50 approvers.
Under this rule, branches in this space cannot be submitted for approval until at least one approver is named, and therefore cannot be merged.
What the approval gate guarantees
-
Only the people the chosen rule allows can approve a branch or request changes: anyone who hasn’t edited the branch, or the named approvers.
-
The person who created a branch can never approve it. Submitting a branch for approval, on the other hand, is open to everyone who can see it.
-
An approval is recorded against the exact branch version and original page version that were reviewed. A later edit on either side invalidates the approval and blocks the merge again.
-
A branch whose original page changed after its last update cannot be submitted for approval. Update it first, so the approver reviews the content that will actually be published.
-
With Only named approvers can approve, an approver who created a branch themselves may merge it without a separate approval, but still cannot review it. That exemption is personal: anyone else merging the same branch needs a real approval. Under Everyone who hasn’t edited the branch can approve, nobody has this exemption.
The day-to-day workflow for authors and approvers is described in Merge Approval.
Approval activity log
Every submission, approval, request for changes, and merge in the space is recorded with the person who acted, the timestamp, the page versions involved, and any comment that was given. The log appears as Approval activity on the space Branches page and is visible to space administrators only, because it names branches and quotes approval comments from across the whole space. Entries remain in the log after a branch page has been merged, archived, or deleted, so the trail outlives the pages it describes.
Permissions requested on upgrade
Merge approval needs two additional Confluence permissions: one to search users for the approver picker, and one to post the comments that notify approvers. A site administrator has to confirm these permissions when the app is upgraded. Until that happens, the new version is not applied.
Branch limit per page
Open branches of the same page work against each other: merging one changes the original page, which makes every other branch of it outdated, and in a space that requires approval their approvals expire. A limit keeps the work on a page in one place.
Turn on Limit branches per page and enter how many active branches a page may have, from 1 to 100. The number is saved when you leave the field, and no limit applies until you enter one. The setting is off by default.
-
Only active branches count. Merged, deleted and trashed branches don’t, so merging or deleting a branch frees its place at once.
-
The limit applies to everyone, space administrators included, whether a branch is created from the byline, the page action menu or the Working Copy agent.
-
Lowering the limit never removes existing branches. A page that already has more branches keeps them all and gets no new one until it is below the limit again.
-
Branches a user can’t open still count, because they are still branches of the page.
A branch can stay on Page Branching’s list after its page was deleted, or when page restrictions leave Page Branching out. Such a branch still counts towards the limit, but nobody can see or delete it. Space administrators can find and remove these branches on the space Branches page – see Space Branches Overview.
Hint for pages with open branches
Editing an original page directly is always allowed, but it makes every branch of the page outdated: each one then needs an Update before it can be merged, which can lead to conflicts, and in a space that requires approval its approval expires. People who edit the page often don’t know that a branch exists.
Turn on Show a hint when someone edits a page that has open branches, and anyone who starts editing a page that has branches sees a banner in the editor. It lists the branches with who created them, and recommends making the change in one of them or checking with whoever created it first. The setting is off by default.
The hint is a recommendation, not a lock. It can be dismissed, never blocks editing or publishing, and Page Branching changes no permissions or restrictions for it. Edits that don’t go through the Confluence editor, such as other apps or Rovo, show no hint. What editors see is described in Creating and Managing Branches.
Permissions
Page Branching uses Confluence’s standard permission model.
-
Users need normal create and edit permission on the original page to create a branch.
-
Space settings can only be changed by space administrators.
-
Branch pages inherit access from the space Branches parent page, so they follow your existing space permissions automatically.
If you need branches to be visible to a smaller group, set page restrictions on the Branches parent page or on individual branches, exactly like you would on any other Confluence page.
Where branches are stored
Branch content is kept as regular Confluence pages under a parent page titled Branches in each space. Because branches are real pages, your existing Confluence backup, search, and audit tooling already covers them – no separate data store to worry about.