merge()

Merge one branch into another with merge, fast-forward-only, or fast-forward-preferred behavior.

TypeScript

const result = await repo.merge({
  sourceBranch: "feature/preview",
  sourceIsEphemeral: true,
  targetBranch: "main",
  targetIsEphemeral: false,
  expectedTargetSha: currentMainSha, // optional optimistic concurrency guard
  strategy: "merge", // "merge" | "ff_only" | "ff_prefer"
  commitMessage: "Merge feature/preview", // optional
  author: { name: "Merge Bot", email: "[e-mail]" }, // optional
  committer: { name: "Merge Bot", email: "[e-mail]" }, // optional
  allowUnrelatedHistories: false, // optional
  squash: false, // optional, incompatible with "ff_only"
});

console.log(result.result); // "merge_commit", "fast_forward", "no_op", or "unknown"
console.log(result.target.oldSha);
console.log(result.target.newSha);

Source and target branches can independently live in the default or ephemeral namespace. Use expectedTargetSha when you want an optimistic concurrency check before updating the target branch.

Options

sourceBranch · string · required

Source branch name to merge from.

sourceIsEphemeral · boolean

Set to true when the source branch lives in the ephemeral namespace.

targetBranch · string · required

Target branch name to merge into.

targetIsEphemeral · boolean

Set to true when the target branch lives in the ephemeral namespace.

strategy · string · required

Merge strategy. Must be one of merge, ff_only, or ff_prefer.

expectedTargetSha · string

Commit SHA that must match the current target tip before the merge is applied.

commitMessage · string

Optional merge commit message. Used when the backend creates a merge commit.

author · object

Optional commit identity with name and email. Required together when provided.

committer · object

Optional committer identity with name and email. Required together when provided.

allowUnrelatedHistories · boolean

Set to true to allow merging branches without a shared history.

squash · boolean

Collapse the source into a single new commit whose only parent is the current target tip. Incompatible with the ff_only strategy.

refPolicies · object[]

Ordered per-ref policy rules ({ pattern, ops? }) embedded in the per-call JWT. First match wins, evaluated against the target ref. Python: ref_policies. Go: RefPolicies with type storage.RefPolicyList. See the Branch Protection guide.

Response

result · string

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.

commitSha · string

Commit SHA reported for the merge result.

treeSha · string

Tree SHA for the resulting commit.

source · object

Source ref metadata with branch, ephemeral, and sha.

target · object

Target ref metadata with branch, ephemeral, and oldSha/old_sha plus newSha/new_sha.

mergeBaseSha · string

Merge base SHA when the backend reports one.

promotedCommits · number

Number of commits promoted onto the target branch.

Errors

Merge conflicts are surfaced as ApiError/APIError. The raw error body is preserved, so conflict responses can still expose backend fields such as conflict_paths and merge_base_sha for callers that need them.