# Merge and rebase branches

Merge and rebase both use a three-way comparison, but move different branches. A merge writes a new version to the target branch. A rebase pulls current Main changes into one active non-Main branch and writes a new version there.

## Preview and complete a merge

Start with **Merge…**, select the target, and generate a **merge preview**. Non-conflicting changes are combined automatically. For ordinary conflicts, the normal resolution uses the most recently changed value. Owners and admins can deliberately choose **Prefer source on every conflict** when the source should win every reported conflict.

![Merge preview from Pickup flow experiment into Main with no conflicts and Main at 100 percent traffic](/docs/product/branch-merge-preview.webp)

Review the source and target tips, each conflict, the resolved configuration, the change note, and the optional **Archive source after merge** setting. The confirmation is bound to exactly that preview. Changing the target, archive option, force option, note, source tip, or target tip invalidates it.

Archiving the source is part of the merge transaction. If the source is Live, its traffic is transferred to the target and a deployment history entry is created. The merge either completes with that traffic change or rolls back as a unit. Drafts belonging to other users are not silently removed.

## Pull changes from Main with rebase

Use **Pull changes from Main** when the working branch should retain its identity but catch up with Main. The rebase preview combines the branch tip with the latest Main tip. When both changed the same field, the branch wins; there is no force-source option for rebase.

Rebase applies only to an active non-Main branch. It does not change Main, does not move traffic, and does not publish a user's draft. Even when the resulting configuration is identical, the new version records lineage so later comparisons have an explicit ancestry path.

## Handle conflicts and stale previews

Read every preview before confirming. Values shown as base, source, and target explain why a field conflicts; the resolved value shows what will be written. Validate referenced resources before execution, especially when one side deleted a Tool, Procedure, Knowledge document, Workflow node, or Guardrail that the other side still uses.

If either tip advances, execution returns a stale preview error and makes no mutation. Refresh, request a new preview, review the new conflict set, and confirm again. Do not reuse a prior preview hash or assume the previous resolution still applies.

Merge and rebase operate on published branch tips, not on an unsaved user draft. When a draft itself is behind its branch tip, use [draft reconciliation](/docs/deploy/reconcile-and-revert). For the branch roles and archive rules that gate these actions, see [deployment overview and branches](/docs/deploy/overview-and-branches).