createBranch()

Create a new branch from an existing branch, optionally using the ephemeral namespace.

const branch = await repo.createBranch({
  baseBranch: "main", // source branch
  targetBranch: "feature/new-onboarding",
  // baseIsEphemeral: true,
  // targetIsEphemeral: true,
});

console.log(branch.targetBranch); // 'feature/new-onboarding'
console.log(branch.commitSha); // tip SHA when available

Toggle baseIsEphemeral/targetIsEphemeral to work with ephemeral refs. The method returns the API message plus the resolved branch metadata so you can confirm creation before pushing commits.

Options

Parameter	Type	Description
baseBranch	Required	Source branch to copy from. Combine with baseIsEphemeral when promoting from the ephemeral namespace.
targetBranch	Required	Destination branch name. May match baseBranch when moving between namespaces.
baseIsEphemeral	Optional	true when the source branch lives in the ephemeral namespace (defaults to false).
targetIsEphemeral	Optional	true to create/update an ephemeral branch instead of the default namespace.

See the Ephemeral Branches guide for concrete promotion examples using these flags.

Response

Field	Type	Description
message	String	Confirmation message
targetBranch (TypeScript) target_branch (Python)	String	The created branch name
targetIsEphemeral (TypeScript) target_is_ephemeral (Python)	Boolean	Whether the branch is in the ephemeral namespace
commitSha (TypeScript) commit_sha (Python)	Optional	The tip commit SHA of the new branch