getEphemeralRemoteURL()

Generate authenticated Git URLs that point to the +ephemeral namespace.

Returns a JWT-authenticated remote URL for the +ephemeral namespace. Refs that you push through this URL do not mirror to an upstream host. They remain separate from refs in the default namespace.

TypeScript

// Default: read/write access, 1-year TTL
const ephemeralUrl = await repo.getEphemeralRemoteURL();
// Returns: https://t:[e-mail]/repo-id+ephemeral.git

// Short-lived URL for a single agent run
const sandboxUrl = await repo.getEphemeralRemoteURL({
  permissions: ['git:read', 'git:write'],
  ttl: 3600,
});

// Disable force push on every ephemeral ref
const safeEphemeralUrl = await repo.getEphemeralRemoteURL({
  refPolicies: [{ pattern: 'refs/namespaces/ephemeral/*', ops: ['no-force-push'] }],
});

Options

permissions · string[]

Array of permissions. Defaults to ["git:read", "git:write"]. Accepts git:read, git:write, repo:write, and org:read. See Authentication for what each scope grants.

ttl · number

Token TTL in seconds. Defaults to 1 year.

refPolicies · object[]

Ordered ref policy rules ({ pattern, ops? }). Code Storage uses the first rule that matches the target ref.

Code Storage stores an ephemeral branch under refs/namespaces/ephemeral/refs/heads/. A plain refs/heads/* pattern does not match it.

Use a complete namespaced pattern or *. Use ref_policies in Python. Use RefPolicies with storage.RefPolicyList in Go.

See getRemoteURL() for operations. See Ref Policies for patterns.

ops · string[] · deprecated

Repo-wide policy ops. The gateway folds them into a catch-all * rule on verify. Use refPolicies instead. See Ref Policies.

Response

Returns a string containing the HTTPS Git remote URL with embedded JWT authentication:

https://t:{jwt}@{org}.code.storage/{repo-id}+ephemeral.git

Usage

Use the URL as a standard Git remote. Push and fetch work with ordinary Git commands:

git remote add ephemeral <url>
git push ephemeral feature-branch
git fetch ephemeral feature-branch

The remote advertises ephemeral refs only. It does not show refs from the default namespace. The normal repository remote does not show ephemeral refs.

See Ephemeral Namespace for promotion workflows and the Connect a Sandbox guide for agent isolation patterns.