createBranch()

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

TypeScript

const branch = await repo.createBranch({
  baseRef: '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.

Create an ephemeral branch from a commit

TypeScript

const stateBranch = await repo.createBranch({
  baseRef: '0123456789abcdef0123456789abcdef01234567',
  targetBranch: 'sessions/agent-123',
  targetIsEphemeral: true,
});

See Ephemeral Namespace for namespace behavior.

Options

baseRef · string

Source branch name, full refs/heads/* ref, full refs/tags/* ref, or full commit SHA. Python: base_ref. Go: BaseRef.

baseBranch · string

Deprecated. Use baseRef instead. A call must include this option or baseRef. When you send both options, baseRef takes precedence. Python: base_branch. Go: BaseBranch.

Only an exact 40-character hexadecimal SHA uses the revision path. An abbreviated SHA or a revision expression returns 400.

targetBranch · string · required

Destination branch name. It can match the source branch name when you move between namespaces.

baseIsEphemeral · boolean

true resolves a branch from the ephemeral namespace. It rejects a tag ref and does not change a full SHA. With the default false, the API rejects all refs/namespaces/* refs, including ephemeral refs.

targetIsEphemeral · boolean

true to create/update an ephemeral branch instead of the default namespace.

refPolicies · object[]

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

message · string

Confirmation message

targetBranch · string

The created branch name

targetIsEphemeral · boolean

Whether the branch is in the ephemeral namespace

commitSha · string

The tip commit SHA of the new branch