Branch Review and Approval

Enabling required reviews

Turn on required reviews under Project Settings > Branches by toggling Require review before merge. Once enabled, the Merge button is disabled on all branches until at least one reviewer has approved. This setting is available on the Pro plan.

Requesting a review

From the branch view in Studio, click Request review and select a teammate from the dropdown. The reviewer receives an email notification. Any editor on the project can request a review.

You can request from more than one reviewer, but a single approval satisfies the gate. If a pending request already exists for the same reviewer, a new request cannot be sent until the existing one is resolved.

Approving or rejecting a branch

The reviewer opens the branch in Studio and clicks Approve or Request changes. Both actions accept an optional comment.

Only the reviewer named in the request can respond. A reviewer cannot approve a request they created. Once a reviewer responds, the request is closed and cannot be updated.

How the approval gate works

When Require review before merge is on, the Merge button stays disabled until at least one review request on the branch has the status approved. A rejected request does not count toward the requirement. After a rejection, the branch author can request a new review from the same or a different reviewer.

Project owners can always merge regardless of approval status. The role hierarchy is: owner > editor > viewer.

Merged branch history

The Branches page in Studio includes a history tab listing every branch that has been merged into main. Each entry shows the branch name, optional description, who created it, who merged it, and when. This log is permanent and cannot be edited after the fact.

Understanding breaking changes after publish

Breaking changes are detected at publish time, not at merge time. After merging a branch and publishing a new release, the publish confirmation flags any tokens that were removed or renamed since the previous published version.

Consumers receive a migration manifest listing each breaking token, the action taken, and a replacement path where one exists. This information also appears in the changelog.

{
  "breakingTokens": [
    {
      "name": "color.brand.primary",
      "action": "renamed",
      "replacedBy": "color.brand.accent"
    },
    {
      "name": "spacing.xl",
      "action": "removed",
      "replacedBy": null
    }
  ]
}

Branch review requests also send a Slack alert to the connected channel. See Notifications and Alerts for setup details.