Merge Approval

In spaces where a space administrator has turned on Merges require approval, a branch cannot be merged into its original page until a named approver has approved it. Everything happens in the Page Branching byline and in the diff view, so there is no separate review tool to learn.

The workflow at a glance

1. Someone edits the branch until it is ready.

2. The branch is submitted for approval, optionally notifying one or more approvers.

3. A named approver opens the diff and approves or requests changes.

4. Once the branch is approved, Merge becomes available again.

Submit a branch for approval

1. Open the branch page in view mode.

2. In the Page Branching byline, find the Merge approval panel.

3. Under Notify, tick the approvers you would like to ask.

4. Click Submit for approval.

Everyone who can see a branch may submit it for approval. Only the decision itself is restricted to approvers.

Each approver you pick is mentioned in a comment on the branch page, which notifies them through the bell, email, and the mobile app. An approver who cannot see the branch page is not notified about it either. Everyone watching the branch page or the space sees these comments as well.

Approve or request changes

Only users who are named as approvers in the space settings can decide on a branch, and the person who created a branch can never approve it.

1. Open the branch page. The Merge approval panel offers Review diff to decide.

2. Read the diff.

3. Optionally add a comment for the branch author.

4. Click Approve or Request changes.

The person who submitted the branch and the branch author are notified of your decision by a comment mention in the same way.

If someone publishes a new version of the branch or the original page while you are still reading the diff, your decision is refused with a note to reload and review the current content. An approval can therefore never cover content that nobody reviewed.

Approval states

The Merge approval panel and the Status column on the space Branches page show where a branch stands:

Why an approval can become outdated

An approval is recorded against the exact branch version and original page version that the approver reviewed, and both version numbers are shown in the panel. Any later edit on either side invalidates the approval and blocks the merge again, so nothing reaches the original page that was not reviewed in the state it is in. Simply submit the branch for approval once more.

Approvers merging their own branches

An approver who created a branch themselves can merge it without asking for a second approval – the panel shows No approval needed. They still cannot review their own branch, and the exemption is personal: if anyone else merges that same branch, it needs a real approval first. Merges of this kind are recorded in the space approval log as merged by an approver without a separate approval.

Approval and updating a branch

Only merges into the original page need an approval. Pulling the latest content from the original page into your branch with Update never requires one, and neither does resolving a conflict along the way (see Merge Conflicts).

Updating a branch does change it, though, so an approval the branch already had becomes outdated afterwards. Bring the branch up to date first and submit it for approval after that, so the approver reviews the content that will actually be published.

Where to see approval activity

• The Merge approval panel on a branch page lists the most recent activity for that branch: who submitted it, who decided, when, and against which page versions.

• The space Branches page adds a Status column for every branch, and space administrators additionally see an Approval activity log for the whole space – see Space Branches Overview.