repos.create

Create a repository.

A repository starts empty or from a source. base_repo is a one-time copy of a Code Storage repository; upstream is a lasting link to an external Git host. A copy takes the history of one commit (base_repo.ref, or the source HEAD) into one branch, and keeps no link to its source. A sync keeps its upstream, and the repository can sync from it again. Set at most one of the two.

A new empty repository has no branch until its first commit. The first commit creates the branch that it targets, so the default branch exists only after a commit to it.

Create is idempotent on the repository name. A new repository returns 201. When the name already exists, the request returns 200, and a copy copies nothing. When the name exists with a different upstream, the request returns 409.

The deprecated form of base_repo, with provider and operation, still works.

Scope: repo:write on the repository.

POST /api/repos

TypeScript

TypeScript

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

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

const repo = await pierre.repos.create({
  base_repo: { auth: { token: 'SOURCE_REPO_READ_TOKEN' }, name: 'pierre/sdk-documentation', ref: 'main' },
  default_branch: 'feature-preview',
  repo_name: 'pierre/docs-copy',
});
console.log(repo);

200

{
  "message": "Repository 'pierre/sdk-documentation' already exists",
  "repo_name": "pierre/sdk-documentation"
}

​

Create an empty repository

Send only repo_name. The new repository uses main as its default branch, or the default_branch that you send. It has no branch until its first commit, so repos.branches.list returns an empty list. The first commit, for example from repos.commits.create, creates the branch that it targets.

TypeScript

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

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

const repo = await pierre.repos.create({ repo_name: 'my-demo-repository' });
console.log(repo);

The other samples of this page copy a repository with base_repo.

Authorizations

Authorization · string · header · required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Query Parameters

default_branch · string

Deprecated: use the default_branch body field instead. Default branch for the new repository. When the body also has default_branch, the body value wins.

Body

application/json

Create an empty repository, a copy of a Code Storage repository (base_repo), or a repository that syncs from an external Git host (upstream).

Create-repository request body. It supplies the optional repository name, default branch, and Git Sync or fork configuration.

base_repo · object

Code Storage repository to copy once. The new repository keeps no link to it. Do not set it together with upstream.

Show child attributes

default_branch · string

Default branch for the new repository. When omitted, a copy takes the default branch of the source, a sync from GitHub takes the default branch of the GitHub repository, and any other repository uses main. An empty repository has no branch until its first commit, and a commit to this name creates the default branch.

Example:

"main"

repo_name · string

Name of the new repository. It can contain a slash.

Example:

"pierre/sdk-documentation"

upstream · object

External Git host to keep syncing from. The link lasts, and the repository can sync again. Do not set it together with base_repo.

Show child attributes

Response

200

application/json

The repository already existed, and the request created nothing.

Result of creating a repository, including its repository name.

http_url · string · required · deprecated

Deprecated: use repo_name. Repository name or path, not a full URL.

Example:

"pierre/sdk-documentation"

message · string · required

Human-readable result: the repository was created, or it already exists. The status gives the same result: 201 or 200.

Example:

"Repository 'pierre/sdk-documentation' created"

repo_id · string · required · deprecated

Deprecated: use repo_name. Stable repository identifier.

Example:

"repo_7f2b3d9"

repo_name · string · required

Repository name or path. It can contain a slash. It matches the JWT repo claim.

Example:

"pierre/sdk-documentation"