expectedTargetSha when you want an optimistic concurrency check before updating the target branch.
Concurrency behavior
merge() has two target-tip modes:
- Provide
expectedTargetShawhen the target branch must still point at a specific commit. If the target moved, the merge fails with409. - Omit
expectedTargetShawhen you want Code Storage to merge into the current target tip. For native Code Storage targets, the gateway may retry stale target or repository movement internally while keeping the originally resolved source commit pinned.
Automatic stale-target retry is disabled for GitHub-backed public targets. Those merges use the
same single-attempt behavior as a strict target-tip guard.
Options
Commit SHA that must match the current target tip before the merge is applied. Providing this
field enables strict optimistic concurrency and disables automatic stale-target retry.
Message of the commit that the merge makes. When you omit it, a merge commit gets the message
Merge branch '<source>' into <target>. Required with squash.Commit identity with
name and email. Required when the merge makes a commit: with merge,
with ff_prefer when a fast-forward is not possible, and with squash.Set to
true to allow merging branches without a shared history.Collapse the source into a single new commit whose only parent is the current target tip.
Incompatible with the
ff_only strategy.Ordered ref policy rules (
{ pattern, ops? }) in the JWT for this call. Code Storage uses the first rule that matches the target ref. Python: ref_policies. Go: RefPolicies with type storage.RefPolicyList. See Ref Policies.Response
Merge outcome:
merge_commit, fast_forward, no_op, or unknown. The Python and Go SDKs also
surface squash. The TypeScript SDK normalizes squash to merge_commit for semver
compatibility.Errors
Merge conflicts and retry exhaustion are surfaced asApiError/APIError. The raw error body is
preserved, so callers can inspect conflict_type and any backend fields included with the response.
conflict_type can be:
merge_conflict: Git found file-level conflicts.conflict_pathsandmerge_base_shamay be present.target_moved: the target branch kept moving during automatic retry. Retry the merge later.repo_changed: repository state changed during automatic retry. Retry the merge later.