Ephemeral Namespace

The +ephemeral namespace stores refs separately from the default namespace. Use it for previews, CI artifacts, and other isolated work. Insert +ephemeral before .git in the repository URL:

git push https://t:JWT@your-org.code.storage/repo-id+ephemeral.git HEAD:preview/pr-123

Two rules apply to every ref that you write through this URL:

A normal git clone does not show the ref. Code Storage puts the ref in the ephemeral namespace. The normal repository URL hides that namespace.
A connected GitHub repository does not receive the ref. Code Storage never mirrors an ephemeral ref to an upstream host.

An ephemeral branch gives you isolation inside one repository. It shares the Git objects and access rules. It remains until you delete or promote it. Promote an ephemeral branch when you want it in the default namespace. Use a fork when you need separate repository access. The other namespace, Import Namespace, accepts a push only and follows different rules.

Setup

Add a named remote when you use the namespace often:

git remote add ephemeral https://t:JWT@your-org.code.storage/repo-id+ephemeral.git

This remote accepts standard Git commands.

Quick start

Push and pull ephemeral branches with standard Git commands:

git push ephemeral feature-branch
git pull ephemeral feature-branch

Promote a branch

Fetch an ephemeral branch. Then push it to the main remote.

git fetch ephemeral feature:feature
git push origin feature

Behavior

Base: Name a base for each ephemeral branch. Use baseBranch / baseRef in the API. When you work with Git, clone the normal remote as your base. The ephemeral remote has no default branch.
Isolation: An ephemeral branch can have the same name as a branch in the default namespace. The two branches remain separate until promotion.
Shared objects: Ephemeral branches reuse Git objects that are already in the repository. This reduces storage use.
HTTP API and Git: Git operations work as usual. HTTP API methods can read and write ephemeral refs when they accept ephemeral or ephemeral_base.

SDK examples

Create an ephemeral branch

In the Python SDK, set ephemeral=True in calls that create commits, read files, or list files. In TypeScript, set ephemeral: true.

// Create an ephemeral branch from "main".
const preview = await repo
  .createCommit({
    targetBranch: 'preview/pr-123',
    baseBranch: 'main',
    ephemeral: true, // Use the ephemeral namespace.
    commitMessage: 'Preview environment for PR 123',
    author: { name: 'CI Bot', email: 'ci@example.com' },
  })
  .addFileFromString('index.html', '<h1>Preview</h1>')
  .send();

// Read a file from the ephemeral branch.
const response = await repo.getFileStream({
  path: 'index.html',
  ref: 'preview/pr-123',
  ephemeral: true, // Read from the ephemeral namespace.
});
const html = await response.text();
console.log(html);

// List files in the ephemeral branch.
const files = await repo.listFiles({
  ref: 'preview/pr-123',
  ephemeral: true,
});
console.log(files.paths);

# Create an ephemeral branch from 'main'.
result = await (
    repo.create_commit(
        target_branch="preview/pr-123",
        base_branch="main",
        ephemeral=True,  # Use the ephemeral namespace.
        commit_message="Preview environment for PR 123",
        author={"name": "CI Bot", "email": "ci@example.com"},
    )
    .add_file_from_string("index.html", "<h1>Preview</h1>")
    .send()
)

# Read a file from the ephemeral branch.
response = await repo.get_file_stream(
    path="index.html",
    ref="preview/pr-123",
    ephemeral=True,  # Read from the ephemeral namespace.
)
content = await response.aread()

# List files in the ephemeral branch.
files = await repo.list_files(
    ref="preview/pr-123",
    ephemeral=True,
)
print(files["paths"])

// Create an ephemeral branch from "main".
builder, err := repo.CreateCommit(storage.CommitOptions{
	TargetBranch:  "preview/pr-123",
	BaseBranch:    "main",
	Ephemeral:     true,
	CommitMessage: "Preview environment for PR 123",
	Author:        storage.CommitSignature{Name: "CI Bot", Email: "ci@example.com"},
})
_, err = builder.AddFileFromString("index.html", "<h1>Preview</h1>", nil).Send(context.Background())

// Read a file from the ephemeral branch.
ephemeral := true
resp, err := repo.FileStream(context.Background(), storage.GetFileOptions{
	Path:      "index.html",
	Ref:       "preview/pr-123",
	Ephemeral: &ephemeral,
})
defer resp.Body.Close()

// List files in the ephemeral branch.
files, err := repo.ListFiles(context.Background(), storage.ListFilesOptions{
	Ref:       "preview/pr-123",
	Ephemeral: &ephemeral,
})
fmt.Println(files.Paths)

Branch from an ephemeral base

Mark the base as ephemeral when another ephemeral branch is the base. You must also set the base branch.

const variant = await repo
  .createCommit({
    targetBranch: 'preview/pr-123-variant',
    baseBranch: 'preview/pr-123',
    ephemeral: true,
    ephemeralBase: true, // Use another ephemeral branch as the base.
    commitMessage: 'Variant of preview environment',
    author: { name: 'CI Bot', email: 'ci@example.com' },
  })
  .addFileFromString('variant.txt', 'This is a variant\n')
  .send();

# Use another ephemeral branch as the base.
result = await (
    repo.create_commit(
        target_branch="preview/pr-123-variant",
        base_branch="preview/pr-123",
        ephemeral=True,
        ephemeral_base=True,  # Use an ephemeral base.
        commit_message="Variant of preview environment",
        author={"name": "CI Bot", "email": "ci@example.com"},
    )
    .add_file_from_string("variant.txt", "This is a variant\n")
    .send()
)

// Use another ephemeral branch as the base.
builder, err := repo.CreateCommit(storage.CommitOptions{
	TargetBranch:  "preview/pr-123-variant",
	BaseBranch:    "preview/pr-123",
	Ephemeral:     true,
	EphemeralBase: true,
	CommitMessage: "Variant of preview environment",
	Author:        storage.CommitSignature{Name: "CI Bot", Email: "ci@example.com"},
})
_, err = builder.AddFileFromString("variant.txt", "This is a variant\n", nil).
	Send(context.Background())

Promote an ephemeral branch

Promote an ephemeral branch to the default namespace. Keep the same branch name or use a new name.

// Keep the same branch name.
await repo.createBranch({
  baseRef: 'preview/pr-123',
  baseIsEphemeral: true,
  targetBranch: 'preview/pr-123',
});

// Use a new target name.
const result = await repo.createBranch({
  baseRef: 'preview/pr-123',
  baseIsEphemeral: true,
  targetBranch: 'feature/awesome-change',
});
console.log(result.targetBranch); // 'feature/awesome-change'

# Keep the same branch name.
result = await repo.create_branch(
    base_ref="preview/pr-123",
    base_is_ephemeral=True,
    target_branch="preview/pr-123",
)

# Use a new target name.
result = await repo.create_branch(
    base_ref="preview/pr-123",
    base_is_ephemeral=True,
    target_branch="feature/awesome-change",
)
print(result["target_branch"])  # "feature/awesome-change"

// Keep the same branch name.
result, err := repo.CreateBranch(context.Background(), storage.CreateBranchOptions{
	BaseRef:         "preview/pr-123",
	BaseIsEphemeral: true,
	TargetBranch:    "preview/pr-123",
})
fmt.Println(result.TargetBranch)

// Use a new target name.
renamed, err := repo.CreateBranch(context.Background(), storage.CreateBranchOptions{
	BaseRef:         "preview/pr-123",
	BaseIsEphemeral: true,
	TargetBranch:    "feature/awesome-change",
})
fmt.Println(renamed.TargetBranch)

This operation keeps the ephemeral branch. Delete that branch when you no longer need it.

Getting Started

Features

Workflows

Reference

Setup

Quick start

Promote a branch

Behavior

SDK examples

Create an ephemeral branch

Branch from an ephemeral base

Promote an ephemeral branch

​Setup

​Quick start

​Promote a branch

​Behavior

​SDK examples

​Create an ephemeral branch

​Branch from an ephemeral base

​Promote an ephemeral branch

Setup

Quick start

Promote a branch

Behavior

SDK examples

Create an ephemeral branch

Branch from an ephemeral base

Promote an ephemeral branch