Repository Forks

A fork is an independent copy of an existing Code Storage repository. It starts from one source commit and has its own access. After the copy, a change in one repository does not reach the other. In the HTTP API, the base_repo field of the create-repository request sets the source. base_repo is a one-time copy of a Code Storage repository; upstream is a lasting link to an external Git host. To keep a repository in sync with another host, see GitHub Sync and Generic Sync.

When to use a fork

Templates: Create new projects from a starter template
Experiments: Test changes in an independent repository
Snapshots: Capture a repository’s state at a specific commit or branch
Isolation: Separate work across a trust or tenant boundary, or give each user an independent project of their own

For per-agent and per-task isolation inside a single repository, use the ephemeral namespace instead. Those branches share the repository’s Git objects and its access, and you can promote the work you keep.

Quick start

Set PIERRE_ORG and PIERRE_PRIVATE_KEY as shown in the Quick Start.

import { GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: process.env.PIERRE_ORG!,
  key: process.env.PIERRE_PRIVATE_KEY!,
});

// Fork at the latest commit (HEAD)
const fork = await store.createRepo({
  id: 'my-fork',
  baseRepo: {
    id: 'template-repo', // Source repository ID
  },
});

// Fork at a specific branch
const branchFork = await store.createRepo({
  id: 'feature-fork',
  baseRepo: {
    id: 'template-repo',
    ref: 'develop', // Fork from tip of 'develop' branch
  },
});

// Fork at a specific commit
const commitFork = await store.createRepo({
  id: 'snapshot-fork',
  baseRepo: {
    id: 'template-repo',
    sha: 'abc123def456...', // Fork at exact commit
  },
});

import os
from pierre_storage import GitStorage

storage = GitStorage({
    "name": os.environ["PIERRE_ORG"],
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

# Fork at the latest commit (HEAD)
fork = await storage.create_repo(
    id="my-fork",
    base_repo={
        "id": "template-repo",  # Source repository ID
    },
)

# Fork at a specific branch
branch_fork = await storage.create_repo(
    id="feature-fork",
    base_repo={
        "id": "template-repo",
        "ref": "develop",  # Fork from tip of 'develop' branch
    },
)

# Fork at a specific commit
commit_fork = await storage.create_repo(
    id="snapshot-fork",
    base_repo={
        "id": "template-repo",
        "sha": "abc123def456...",  # Fork at exact commit
    },
)

ctx := context.Background()

// Fork at the latest commit (HEAD)
fork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: "my-fork",
	BaseRepo: storage.ForkBaseRepo{
		ID: "template-repo",
	},
})

// Fork at a specific branch
branchFork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: "feature-fork",
	BaseRepo: storage.ForkBaseRepo{
		ID:  "template-repo",
		Ref: "develop",
	},
})

// Fork at a specific commit
commitFork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
	ID: "snapshot-fork",
	BaseRepo: storage.ForkBaseRepo{
		ID:  "template-repo",
		SHA: "abc123def456...",
	},
})

# SOURCE_TOKEN is a JWT with git:read on template-repo.
curl "$PIERRE_API_BASE_URL/repos" \
  -X POST \
  -H "Authorization: Bearer $PIERRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_name": "feature-fork",
    "base_repo": {
      "name": "template-repo",
      "ref": "develop",
      "auth": { "token": "'"$SOURCE_TOKEN"'" }
    }
  }'

baseRepo takes id, ref, and sha. In the HTTP API, base_repo takes name, ref, and auth.token. ref accepts a branch, a tag, or a commit SHA, and defaults to the HEAD of the source. The new default branch is the top-level default_branch, or else the default branch name of the source. See createRepo() for the full parameter list and resolution order. That page also explains which default branch the fork inherits.

Use cases

Project templates

Create new projects from a starter template:

async function createProjectFromTemplate(templateId: string, projectName: string, userId: string) {
  const project = await store.createRepo({
    id: `${userId}/${projectName}`,
    baseRepo: { id: templateId },
  });

  // Customize the new project
  await project
    .createCommit({
      targetBranch: 'main',
      commitMessage: 'Initialize project',
      author: { name: 'System', email: 'system@example.com' },
    })
    .addFileFromString('README.md', `# ${projectName}\n\nCreated by ${userId}`)
    .send();

  return project;
}

// Usage
const project = await createProjectFromTemplate(
  'templates/react-starter',
  'my-new-app',
  'user-123',
);

async def create_project_from_template(
    template_id: str,
    project_name: str,
    user_id: str
):
    project = await storage.create_repo(
        id=f"{user_id}/{project_name}",
        base_repo={"id": template_id},
    )

    # Customize the new project
    commit = project.create_commit(
        target_branch="main",
        commit_message="Initialize project",
        author={"name": "System", "email": "system@example.com"},
    )
    commit.add_file_from_string(
        "README.md",
        f"# {project_name}\n\nCreated by {user_id}"
    )
    await commit.send()

    return project

# Usage
project = await create_project_from_template(
    "templates/react-starter",
    "my-new-app",
    "user-123"
)

func createProjectFromTemplate(ctx context.Context, templateID, projectName, userID string) (*storage.Repo, error) {
	// Fork the template repo
	project, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
		ID:       userID + "/" + projectName,
		BaseRepo: storage.ForkBaseRepo{ID: templateID},
	})
	if err != nil {
		return nil, err
	}

	// Customize the new project
	builder, err := project.CreateCommit(storage.CommitOptions{
		TargetBranch:  "main",
		CommitMessage: "Initialize project",
		Author:        storage.CommitSignature{Name: "System", Email: "system@example.com"},
	})
	if err != nil {
		return nil, err
	}

	_, err = builder.AddFileFromString(
		"README.md",
		"# "+projectName+"\n\nCreated by "+userID,
		nil,
	).Send(ctx)
	if err != nil {
		return nil, err
	}

	return project, nil
}

// Usage
project, err := createProjectFromTemplate(context.Background(), "templates/react-starter", "my-new-app", "user-123")

Point-in-time snapshots

Capture a repository’s state before you make risky changes:

async function createSnapshot(repoId: string, label: string) {
  const source = await store.findOne({ id: repoId });
  const commits = await source.listCommits({ limit: 1 });
  const headSha = commits.commits[0].sha;

  const snapshot = await store.createRepo({
    id: `snapshots/${repoId}/${label}`,
    baseRepo: {
      id: repoId,
      sha: headSha,
    },
  });

  return snapshot;
}

// Before a major refactor
const backup = await createSnapshot('my-project', 'pre-refactor-2024-01');

async def create_snapshot(repo_id: str, label: str):
    source = await storage.find_one(id=repo_id)
    commits = await source.list_commits(limit=1)
    head_sha = commits["commits"][0]["sha"]

    snapshot = await storage.create_repo(
        id=f"snapshots/{repo_id}/{label}",
        base_repo={
            "id": repo_id,
            "sha": head_sha,
        },
    )

    return snapshot

# Before a major refactor
backup = await create_snapshot("my-project", "pre-refactor-2024-01")

func createSnapshot(ctx context.Context, repoID, label string) (*storage.Repo, error) {
	// Capture the current HEAD SHA
	source, err := client.FindOne(ctx, storage.FindOneOptions{ID: repoID})
	if err != nil {
		return nil, err
	}
	commits, err := source.ListCommits(ctx, storage.ListCommitsOptions{Limit: 1})
	if err != nil {
		return nil, err
	}
	headSHA := commits.Commits[0].SHA

	// Fork at the captured commit
	return client.CreateRepo(ctx, storage.CreateRepoOptions{
		ID: "snapshots/" + repoID + "/" + label,
		BaseRepo: storage.ForkBaseRepo{
			ID:  repoID,
			SHA: headSHA,
		},
	})
}

// Before a major refactor
backup, err := createSnapshot(context.Background(), "my-project", "pre-refactor-2024-01")

Fork or sync

`operation`	Source	Ongoing connection	Best for
`fork`	A Code Storage repository	No	Templates, snapshots, isolated copies
`sync`	An external Git provider	Yes	Repositories that should stay mirrored

In the HTTP API, a fork is base_repo and a sync is upstream. Set at most one of them in a request. A request with both returns HTTP 400.

Copy a GitHub repository

A fork needs a Code Storage source. To copy a public GitHub repository, create a repository with a public GitHub upstream instead. It needs no GitHub App:

{
  "repo_name": "my-copy",
  "upstream": {
    "provider": "github",
    "owner": "octocat",
    "name": "hello-world",
    "access": "public"
  }
}

Public GitHub mode runs one import and keeps no continuous sync. The repository keeps its link to GitHub, so it can sync again on request.

Limitations

Same organization: You can only fork repositories within your own organization
No relationship tracking: Forks are independent. Code Storage keeps no “parent” reference after creation. No route merges a fork back into its source
No upstream: A fork records no upstream, so pullUpstream() on a fork returns HTTP 400 with repository has no upstream configured. To get later changes, add the source repository as a second Git remote. Fetch and merge the changes
One branch: A fork has one branch, at the chosen commit, with the history of that commit. It has no other branches and no tags

Getting Started

Platform

Workflows

Libraries

API Reference

When to use a fork

Quick start

Use cases

Project templates

Point-in-time snapshots

Fork or sync

Copy a GitHub repository

Limitations

​When to use a fork

​Quick start

​Use cases

​Project templates

​Point-in-time snapshots

​Fork or sync

​Copy a GitHub repository

​Limitations

When to use a fork

Quick start

Use cases

Project templates

Point-in-time snapshots

Fork or sync

Copy a GitHub repository

Limitations