Skip to content

Create & connect a repository

You need a project and permission to create repositories in it. The repository must reach ready before its clone_url is available.

In the console, open Project → Repositories → Create repository, enter a name, and select Create repository. The detail page shows its status and, once ready, lets you copy the clone URL or clone command.

You can also create one with the Cloud API. Use a cwt_ or cwp_ token with repository:write and a project-scoped Idempotency-Key:

API request
POST /v1/projects/{projectId}/repositories
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: create-web-001
{ "name": "Web source" }

Names are trimmed display text of 1–100 characters. A ready create returns 201 with this response shape (IDs and timestamps are examples):

201 Created
{
"repository": {
"repository_id": "0195a1b2-c3d4-7e5f-8901-23456789abcd",
"project_id": "<projectId>",
"name": "Web source",
"status": "ready",
"clone_url": "https://git.cloud.comwit.io/<projectId>/0195a1b2-c3d4-7e5f-8901-23456789abcd.git",
"retry": "none",
"created_at": "2026-09-24T00:00:00Z",
"updated_at": "2026-09-24T00:00:00Z"
}
}

A create still in progress returns 202 with the same repository wrapper, status: "pending", and a retry value. It has no clone_url yet. Reuse the same key and name if retry becomes retry_create; changing the name for that key returns 409. See Manage repositories for the other status and retry values.

This extension requires the initialization-capable API/schema and Gitcask release; check the deployed OpenAPI before using it. The console form still creates an empty repository. For the API, add a Cloud source repository ID and its full, nonzero, lowercase 40-character SHA-1 commit hash:

{
"name": "My application",
"initialize_from": {
"repository_id": "<sourceRepositoryId>",
"commit_sha": "0123456789abcdef0123456789abcdef01234567"
}
}

Use this body with the same POST route and a new Idempotency-Key. Source IDs must identify existing ready Cloud repositories. URLs, branch names, tags, abbreviated hashes, and SHA-256 commits are not accepted: Cloud currently creates SHA-1 repositories. Missing and inaccessible source repositories both return 404. A token without repository:read is rejected with 403 before source lookup. Both repository:read for the source and repository:write for the destination are required. A human may read a source in another project only with current access to both projects; a project token can use only its own project. Internal server-token callers must forward the real human actor, whose source read and destination write memberships are checked independently.

The result has a fresh root commit on main containing the source commit’s tree, without its commit history. Gitcask stores independent target objects, so deleting the source afterward does not remove target contents. Commit identity is Comwit Cloud <noreply@comwit.io> with message Initial commit; the original request’s timestamp is retained through retries. Gitlinks and .gitmodules are preserved without fetching submodules. Git LFS pointer trees are rejected because initialization does not copy LFS payloads.

The existing repository response includes initialize_from provenance and, once ready, default_branch, initial_commit_sha, and initial_tree_sha. These describe initialization, not the branch’s current tip after later pushes. Ready requires the new commit to exist durably; pending responses have no clone URL or Git grants. A ready initialized repository can be cloned immediately.

Retry retry_create with the exact original name, source ID/hash and key. Changing or removing initialize_from for that key returns 409. A timeout during initialization can be retried using the persisted operation; it does not create a second repository or commit. Each upstream call has a five-second timeout; work may continue after it. An ambiguous initialization result keeps a durable two-minute cooldown (retry: in_progress, with Retry-After seconds on create/detail) so rapid retries do not consume attempts. Cloud has no background completion worker; completion is discovered by the next permitted POST retry. After that interval, repeat the same POST when retry_create is shown. Confirmed-target initialization remains safely retryable after any number of ambiguous replies; the five-attempt pre-create budget does not prevent recovery of a committed receipt. Successful intent replay remains possible after source deletion while the caller retains source-project read permission. A new intent cannot use a deleted source. Current permissions are checked on every retry, including completed requests.

Creation ambiguity, initialization conflict/rejection, or five failed pre-create checks require reconciliation. initialization_unconfirmed permits an identical retry when retry says retry_create; initialization_conflict and initialization_rejected require operator investigation (for example an unavailable source commit, incompatible format, size limit, or LFS pointer). Pending initialized repositories cannot be deleted through this API (409), even after failure: upstream work can survive a disconnected client. Do not retry with a different key to repair the same uncertain intent. Automatic E2B provisioning is outside this capability.

Install the comwit CLI and sign in:

Terminal window
comwit login

Login saves your token and configures a Git credential helper for git.cloud.comwit.io. Copy the clone_url from the ready repository, then:

Terminal window
CLONE_URL="https://git.cloud.comwit.io/<projectId>/<repositoryId>.git"
git clone "$CLONE_URL"
cd <repositoryId>

Replace the IDs with the values from your repository. Git uses the token saved by comwit login, so it should not ask for a password when the helper is configured successfully.

For a new empty repository, add your project files and push a first commit:

Terminal window
git add .
git commit -m "Initial commit"
git push -u origin HEAD

Pushing requires repository:write. To track large files, install Git LFS in your Git environment and track the desired file types before committing; LFS objects use the same Git host.

For CI, use a project cwp_ token with the scopes your job needs. Configure your CI Git credential mechanism to provide any username and that token as the HTTPS Basic password for git.cloud.comwit.io. A read-only clone job should select repository:read; a push job needs repository:write, which also allows cloning. Do not put the token in the clone URL or commit it to the repository.