repos.branches.create

POST

api

repos

{repo_name}

branches

create

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const branch = await pierre.repos.branches.create({
  repo_name: 'my-demo-repository',
  base_ref: 'main',
  target_branch: 'feature/new-onboarding',
});
console.log(branch);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

branch = pierre.repos.branches.create(
    repo_name="my-demo-repository",
    base_ref="main",
    target_branch="feature/new-onboarding",
)
print(branch)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
branch, err := client.Repos.Branches.Create(ctx, pierre.ReposBranchesCreateParams{
	RepoName:     "my-demo-repository",
	BaseRef:      pierre.String("main"),
	TargetBranch: pierre.String("feature/new-onboarding"),
})
if err != nil {
	return err
}
fmt.Println(branch)

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/branches/create" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_ref": "main",
    "target_branch": "feature/new-onboarding"
  }'

{
  "commit_sha": "abc123def4567890abc123def4567890abc123de",
  "message": "branch created",
  "target_branch": "feature/new-onboarding",
  "target_is_ephemeral": false
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Guard a branch write

Set expected_target_sha to control whether the branch can change:

Value	Required target state
`0000000000000000000000000000000000000000`	The branch must not exist.
A full commit SHA	The branch must exist at that commit.
Omitted or empty	No caller-supplied tip guard.

A failed guard returns HTTP 409 with code conflict and leaves the branch unchanged. The guard applies with or without force. It also applies to ephemeral branches. force permits a non-fast-forward move, subject to the token’s ref policies; it does not bypass the guard. For example, create a branch only when its name is available:

{
  "base_ref": "main",
  "target_branch": "feature/new-onboarding",
  "expected_target_sha": "0000000000000000000000000000000000000000"
}

To move a branch, set base_ref to the destination commit and expected_target_sha to its current tip. A non-zero guard requires target_branch. Without target_branch, the server allocates a new name with a create-only guard.

Authorizations

Authorization

string

header

required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Scopes

git:write

Path Parameters

repo_name

string

required

The repository name, for example acme/web.

Body

application/json

Create or move a branch from another branch or ref. The source and destination can live in the default namespace or the ephemeral namespace. Set expected_target_sha to 40 zeros to require a new branch, or to the current tip to guard a move. A failed guard returns 409 conflict without changing the branch, even with force.

Create-branch request body describing the new branch and its base ref.

base_branch

string

deprecated

Deprecated: use base_ref. Preferred source branch name.

base_is_ephemeral

boolean

Whether the base branch should be resolved from the ephemeral namespace.

Example:

false

base_ref

string

Optional source ref or revision. Provide base_ref or the deprecated base_branch.

Example:

"main"

expected_target_sha

string

Optional full commit SHA that must match the target branch tip. Set to 40 zeros to require a new branch. A non-zero guard requires target_branch. Empty means no guard. Applies with or without force.

force

boolean

Allow non-fast-forward updates when recreating an existing named branch. Requires target_branch.

preferred_base

string

Optional pack hint. A branch name the backend prefers as the delta base when it builds the thin pack. It does not change the source or the result.

target_branch

string

Optional destination branch name. Omit it to let the server allocate a name.

Example:

"feature/new-onboarding"

target_is_ephemeral

boolean

Whether the new branch should be created in the ephemeral namespace.

Example:

false

Response

Branch creation result.

Result of creating a branch, including the resulting ref state.

message

string

required

Human-readable result message.

Example:

"branch created"

target_branch

string

required

Destination branch name.

Example:

"feature/new-onboarding"

target_is_ephemeral

boolean

required

Whether the created branch is ephemeral.

Example:

false

commit_sha

string

Resolved commit SHA at the new branch tip.

Example:

"abc123def4567890abc123def4567890abc123de"

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const branch = await pierre.repos.branches.create({
  repo_name: 'my-demo-repository',
  base_ref: 'main',
  target_branch: 'feature/new-onboarding',
});
console.log(branch);

from pierre import Pierre

# The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
pierre = Pierre()

branch = pierre.repos.branches.create(
    repo_name="my-demo-repository",
    base_ref="main",
    target_branch="feature/new-onboarding",
)
print(branch)

import (
	"context"
	"fmt"

	pierre "github.com/pierrecomputer/sdk/go"
)

ctx := context.Background()
// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
client, err := pierre.NewClient()
if err != nil {
	return err
}
branch, err := client.Repos.Branches.Create(ctx, pierre.ReposBranchesCreateParams{
	RepoName:     "my-demo-repository",
	BaseRef:      pierre.String("main"),
	TargetBranch: pierre.String("feature/new-onboarding"),
})
if err != nil {
	return err
}
fmt.Println(branch)

curl -X POST \
  "https://api.{org}.code.storage/api/repos/my-demo-repository/branches/create" \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_ref": "main",
    "target_branch": "feature/new-onboarding"
  }'

{
  "commit_sha": "abc123def4567890abc123def4567890abc123de",
  "message": "branch created",
  "target_branch": "feature/new-onboarding",
  "target_is_ephemeral": false
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>",
  "invalid_params": [
    {
      "name": "deployment.production_branch",
      "reason": "exceeds 255 characters"
    }
  ]
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

{
  "code": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "error": "<string>",
  "instance": "<string>"
}

Getting Started

Platform

Workflows

Libraries

API Reference

Guard a branch write

Authorizations

Scopes

Path Parameters

Body

Response