> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# createRepo()

> Create a new repository with optional custom ID, default branch, Git Sync configuration, or a fork from an existing repository.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // Basic repository creation (defaults to 'main' branch)
  const repo = await store.createRepo();

  // With custom ID
  const repo = await store.createRepo({
    id: 'my-custom-repo',
  });

  // With custom default branch
  const repo = await store.createRepo({
    id: 'my-custom-repo',
    defaultBranch: 'develop',
  });

  // With namespacing
  const repo = await store.createRepo({
    id: 'production/api-service',
    defaultBranch: 'production',
  });

  // Fork from existing repository
  const fork = await store.createRepo({
    id: 'my-fork',
    baseRepo: {
      id: 'source-repo', // Repository to fork from
      ref: 'main', // Optional: branch to fork from
    },
  });
  ```

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  from pierre_storage import GitStorage

  storage = GitStorage({
      "name": "your-org",          # Your organization identifier
      "key": "your-private-key",   # Your API key in PEM format
  })

  repo = await storage.create_repo()
  print(repo.id)  # e.g., '123e4567-e89b-12d3-a456-426614174000'

  custom_repo = await storage.create_repo(id="my-custom-repo")
  print(custom_repo.id)  # 'my-custom-repo'

  # Git sync (GitHub example)
  github_repo = await storage.create_repo(
      id="my-synced-repo",
      base_repo={
          "owner": "octocat",
          "name": "Hello-World",
          "default_branch": "main",  # optional
      },
  )
  # This repository will sync with github.com/octocat/Hello-World

  # Fork from existing repository
  fork = await storage.create_repo(
      id="my-fork",
      base_repo={
          "id": "source-repo",  # Repository to fork from
          "ref": "main",        # Optional: branch to fork from
      },
  )
  ```

  ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  ctx := context.Background()

  // Create a new repository
  repo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{})

  // Create a repository with a custom ID
  customRepo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
  	ID: "my-custom-repo",
  })

  // Create a repository with Git sync (GitHub example)
  githubRepo, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
  	ID: "my-synced-repo",
  	BaseRepo: storage.GitHubBaseRepo{
  		Owner:         "octocat",
  		Name:          "Hello-World",
  		DefaultBranch: "main",
  	},
  })

  // Fork from an existing repository
  fork, err := client.CreateRepo(ctx, storage.CreateRepoOptions{
  	ID: "my-fork",
  	BaseRepo: storage.ForkBaseRepo{
  		ID:  "source-repo",
  		Ref: "main",
  	},
  })
  ```
</CodeGroup>

## Options

<ParamField path="id" type="string">
  Repository ID. If not provided, a UUID will be auto-generated. Supports namespacing with `/`
  (e.g., `team/project-alpha`).
</ParamField>

<ParamField path="defaultBranch" type="string">
  Default branch name for the repository. Defaults to `main`.
</ParamField>

<ParamField path="baseRepo" type="object">
  Configuration for Git Sync or forking from an existing repository. See below for structure.
</ParamField>

<ParamField path="ttl" type="string">
  Token TTL for this invocation in seconds. Defaults to 1 hour when omitted for this call.
</ParamField>

## BaseRepo for Git Sync

Use this structure to sync with a GitHub repository:

<ParamField path="owner" type="string" required>
  GitHub repository owner (username or organization).
</ParamField>

<ParamField path="name" type="string" required>
  GitHub repository name.
</ParamField>

<ParamField path="defaultBranch" type="string">
  GitHub repository's default branch.
</ParamField>

## BaseRepo for Forking

Use this structure to fork from an existing Code Storage repository:

<ParamField path="id" type="string" required>
  The source repository ID to fork from.
</ParamField>

<ParamField path="ref" type="string">
  Branch or tag name to fork from. Forks the tip of this ref.
</ParamField>

<ParamField path="sha" type="string">
  Exact commit SHA to fork at. Overrides `ref` if both are provided.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The repository identifier
</ResponseField>

<ResponseField name="defaultBranch" type="string">
  The repository's default branch name (e.g., `main`)
</ResponseField>

## BaseRepo for Git Sync

Use this structure to sync with a GitHub repository:

> When `baseRepo` contains `owner` and `name`, Code Storage links the repository to an external Git
> provider for syncing. See the [Integrations guide](/docs/guides/integrations) for details.

> Generic Git providers such as GitLab, Bitbucket, Gitea, Forgejo, Codeberg, and SourceHut use the
> same repository creation flow at the HTTP API layer. After creating the repo, configure
> credentials with [Git credentials](/docs/reference/api/repositories/create-generic-git-credential).

## BaseRepo for Forking

Use this structure to fork from an existing Code Storage repository:

> When `baseRepo` contains `id`, a fork is created from the specified repository. See the
> [Forking guide](/docs/guides/forking) for details.

## Response

Returns a `Repository` instance with the following properties:

The returned repository instance also provides methods for managing branches, commits, files, and
more. See the other SDK reference pages for details.