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.
1. Create the repository
Section titled “1. Create the repository”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:
POST /v1/projects/{projectId}/repositoriesAuthorization: Bearer <token>Content-Type: application/jsonIdempotency-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):
{ "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.
Initialize from a pinned source commit
Section titled “Initialize from a pinned source commit”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.
2. Log in and clone
Section titled “2. Log in and clone”Install the comwit CLI and sign in:
comwit loginLogin saves your token and configures a Git credential helper for
git.cloud.comwit.io. Copy the clone_url from the ready repository, then:
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.
3. Commit and push
Section titled “3. Commit and push”For a new empty repository, add your project files and push a first commit:
git add .git commit -m "Initial commit"git push -u origin HEADPushing 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.
CI and manual credentials
Section titled “CI and manual credentials”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.