Ephemeral Namespace

Create isolated refs for previews, CI artifacts, and experiments. Promote an ephemeral branch to the default 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:[e-mail]/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:[e-mail]/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: base_branch in repos.commits.create, or base_ref in repos.branches.create. 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. An operation reads an ephemeral ref when you set its ephemeral field, and writes one when you set target_is_ephemeral. base_is_ephemeral and source_is_ephemeral read the base or the source from the ephemeral namespace.

​

SDK examples

​

Create an ephemeral branch

Set target_is_ephemeral to write a commit to the ephemeral namespace. Set ephemeral to read or list the files of an ephemeral branch. In Go, the fields are TargetIsEphemeral and Ephemeral.

TypeScript

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

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

// Create an ephemeral branch from "main".
const preview = await pierre.repos.commits.create({
  repo_name: 'acme/web',
  target_branch: 'preview/pr-123',
  base_branch: 'main',
  target_is_ephemeral: true, // Write to the ephemeral namespace.
  commit_message: 'Preview environment for PR 123',
  author: { name: 'CI Bot', email: '[e-mail]' },
  files: [{ path: 'index.html', content: '<h1>Preview</h1>' }],
});
console.log(preview.commit.commit_sha);

// Read a file from the ephemeral branch.
const response = await pierre.repos.files.get({
  repo_name: 'acme/web',
  path: 'index.html',
  ref: 'preview/pr-123',
  ephemeral: true, // Read from the ephemeral namespace.
});
console.log(await response.text());

// List files in the ephemeral branch.
const files = await pierre.repos.files.list({
  repo_name: 'acme/web',
  ref: 'preview/pr-123',
  ephemeral: true,
});
console.log(files.body.paths);

​

Branch from an ephemeral base

Set base_is_ephemeral when another ephemeral branch is the base. Also set base_branch.

TypeScript

const variant = await pierre.repos.commits.create({
  repo_name: 'acme/web',
  target_branch: 'preview/pr-123-variant',
  base_branch: 'preview/pr-123',
  base_is_ephemeral: true, // Use another ephemeral branch as the base.
  target_is_ephemeral: true,
  commit_message: 'Variant of preview environment',
  author: { name: 'CI Bot', email: '[e-mail]' },
  files: [{ path: 'variant.txt', content: 'This is a variant\n' }],
});
console.log(variant.commit.commit_sha);

​

Promote an ephemeral branch

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

TypeScript

// Keep the same branch name.
await pierre.repos.branches.create({
  repo_name: 'acme/web',
  base_ref: 'preview/pr-123',
  base_is_ephemeral: true,
  target_branch: 'preview/pr-123',
});

// Use a new target name.
const promoted = await pierre.repos.branches.create({
  repo_name: 'acme/web',
  base_ref: 'preview/pr-123',
  base_is_ephemeral: true,
  target_branch: 'feature/awesome-change',
});
console.log(promoted.target_branch); // 'feature/awesome-change'

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