Code Storage

── ENVIRONMENT SETUP ─────────────────────────────────────────────────────────

Required Environment Variables

Export for curl sessions:

export ORG_NAME="your-org"
export CODE_STORAGE_BASE_URL="https://api.${ORG_NAME}.code.storage/api/v1"
export CODE_STORAGE_TOKEN="YOUR_JWT_TOKEN"

JWT Token Structure

Every request requires a JWT signed with your private key. Tokens are per-repository (except org:read which is org-wide).

{
  "iss": "your-org",          // Organization identifier
  "sub": "agent-id",          // Agent/pipeline identity (for logging)
  "repo": "team/project",     // Repository the token grants access to
  "scopes": ["git:read", "git:write"],
  "iat": 1723453189,
  "exp": 1723456789
}

JWT header: { "alg": "ES256", "typ": "JWT" } (RS256 also supported)

Permission Scopes

Git Remote URL Format

https://t:{JWT}@{ORG_NAME}.code.storage/{REPO_ID}.git

Username is always t. Password is the JWT.

── QUICK-REFERENCE ENDPOINT TABLE ───────────────────────────────────────────

All endpoints: BASE_URL = https://api.{org}.code.storage/api/v1 All requests: Authorization: Bearer $CODE_STORAGE_TOKEN

── ENDPOINT REFERENCE ────────────────────────────────────────────────────────

POST /repos — Create Repository

curl "$CODE_STORAGE_BASE_URL/repos" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_branch": "main"}'

With GitHub Sync:

{
  "default_branch": "main",
  "base_repo": { "provider": "github", "owner": "ORG", "name": "REPO", "default_branch": "main" }
}

With generic HTTPS Git Sync:

{
  "default_branch": "main",
  "base_repo": {
    "provider": "gitlab",
    "owner": "GROUP",
    "name": "REPO",
    "default_branch": "main"
  }
}

Generic providers include gitlab, bitbucket, gitea, forgejo, codeberg, sr.ht, and sourcehut. For self-hosted providers, include upstream_host, for example "upstream_host": "git.example.com". After creating a generic Git Sync repository, store upstream credentials with /repos/git-credentials.

Fork from existing Code Storage repo:

{
  "base_repo": {
    "provider": "code.storage",
    "name": "source-repo-id",
    "operation": "fork",
    "ref": "main",
    "auth": { "token": "JWT_WITH_GIT_READ_ON_SOURCE" }
  }
}

Forking also supports sha to pin an exact source commit; sha overrides ref.

Response 201: { "repo_id": "...", "http_url": "team/project", "message": "..." } Errors: 401 bad JWT/scope, 409 repo already exists or upstream already configured, 412 GitHub App config required for authenticated GitHub sync

POST/PUT/DELETE /repos/git-credentials — Manage Generic Git Sync Credentials

Use this endpoint family for generic HTTPS Git providers such as GitLab, Bitbucket, Gitea, Forgejo, Codeberg, SourceHut, and self-hosted remotes.

# Create credential
curl "$CODE_STORAGE_BASE_URL/repos/git-credentials" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_id":"REPO_ID","username":"git","password":"ACCESS_TOKEN_OR_PASSWORD"}'

# Update credential
curl "$CODE_STORAGE_BASE_URL/repos/git-credentials" -X PUT \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"CREDENTIAL_ID","username":"git","password":"ROTATED_ACCESS_TOKEN"}'

# Delete credential
curl "$CODE_STORAGE_BASE_URL/repos/git-credentials" -X DELETE \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"CREDENTIAL_ID"}'

username is optional for token-only providers. A repository can have one stored Git credential. GitHub App sync does not use this endpoint.

GET /repos — List Repositories

curl "$CODE_STORAGE_BASE_URL/repos?limit=20&cursor=CURSOR" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Params: cursor (pagination), limit (default 20, max 100) Scope: org:read Response: { "repos": [...], "next_cursor": "...", "has_more": true }

GET /repo — Get Repository

curl "$CODE_STORAGE_BASE_URL/repo" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Repository identified from JWT repo claim. Response: { "repo_id", "url", "default_branch", "created_at", "base_repo?" }

DELETE /repos/delete — Delete Repository

curl "$CODE_STORAGE_BASE_URL/repos/delete" -X DELETE \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Scope: repo:write. Deletion is async; physical storage cleanup completes asynchronously. Errors: 403 missing scope, 404 not found, 409 already deleted

POST /repos/branches/create — Create Branch

curl "$CODE_STORAGE_BASE_URL/repos/branches/create" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_branch":"main","target_branch":"feature/x","base_is_ephemeral":false,"target_is_ephemeral":false}'

Optional: force (bool), preferred_base (string), base_is_ephemeral, target_is_ephemeral Response: { "message", "target_branch", "target_is_ephemeral", "commit_sha" }

GET /repos/branches — List Branches

curl "$CODE_STORAGE_BASE_URL/repos/branches?limit=20&cursor=CURSOR" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Response: { "branches": [{ "name", "head_sha", "created_at" }], "next_cursor", "has_more" }

GET /repos/branches/diff — Get Branch Diff

curl "$CODE_STORAGE_BASE_URL/repos/branches/diff?branch=BRANCH&base=main&path=src/foo.go" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Params: branch(required), base, ephemeral, ephemeral_base, path (repeatable) Response: { "branch", "base", "stats": {files,additions,deletions,changes}, "files": [...], "filtered_files": [...] } State codes in files[].state: A=added, M=modified, D=deleted, R=renamed

DELETE /repos/branches — Delete Branch

curl "$CODE_STORAGE_BASE_URL/repos/branches" -X DELETE \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"feature/old-onboarding"}'

The default branch cannot be deleted. If the repository is connected to GitHub sync, branch deletion triggers a sync automatically. Response: { "name": "feature/old-onboarding", "message": "branch deleted" }

POST /repos/commit-pack — Create Commit

Content-Type: application/x-ndjson Send metadata line first, then blob_chunk lines.

{"metadata":{"target_branch":"main","commit_message":"msg","author":{"name":"Bot","email":"bot@x.com"},"files":[{"path":"README.md","operation":"upsert","content_id":"b1","mode":"100644"}]}}
{"blob_chunk":{"content_id":"b1","data":"BASE64_CONTENT","eof":true}}

Key metadata fields: target_branch, commit_message, author* (name+email), files*, expected_head_sha, base_branch, committer, ephemeral, ephemeral_base File operations: upsert (default) or delete. For delete, omit blob chunks; only the metadata entry is required. data is base64; decoded chunks must be 4 MiB or smaller. Response 201: { "commit": { "commit_sha", "tree_sha", "target_branch", "pack_bytes", "blob_count" }, "result": { "branch", "old_sha", "new_sha", "success", "status", "message" } } Errors: 409 head SHA mismatch, 404 base branch not found

POST /repos/diff-commit — Create Commit from Diff

Content-Type: application/x-ndjson Same pattern as commit-pack but uses diff_chunk instead of blob_chunk.

{"metadata":{"target_branch":"main","commit_message":"Apply patch","author":{"name":"Bot","email":"bot@x.com"}}}
{"diff_chunk":{"data":"BASE64_ENCODED_DIFF","eof":true}}

Diff must be compatible with git apply --cached --binary. Same response schema as commit-pack.

GET /repos/commits — List Commits

curl "$CODE_STORAGE_BASE_URL/repos/commits?branch=main&limit=20&cursor=CURSOR" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Response: { "commits": [{ "sha", "message", "author_name", "author_email", "date" }], "next_cursor", "has_more" }

GET /repos/diff — Get Commit Diff

curl "$CODE_STORAGE_BASE_URL/repos/diff?sha=COMMIT_SHA&baseSha=OPTIONAL_BASE&path=src/foo.go" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Params: sha(required), baseSha, path (repeatable) Response: { "sha", "stats", "files": [...], "filtered_files": [...] } Large files (>500KB) or binary files appear in filtered_files without diff content.

POST /repos/restore-commit — Restore Branch to Commit

Content-Type: application/x-ndjson

{"metadata":{"target_branch":"main","target_commit_sha":"abc123...","author":{"name":"Bot","email":"bot@x.com"},"commit_message":"Rollback"}}

Optional: expected_head_sha (guard), committer Response: same schema as commit-pack result.

GET /repos/files — List Files

curl "$CODE_STORAGE_BASE_URL/repos/files?ref=main&ephemeral=false" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Params: ref (branch/SHA, defaults to default branch), ephemeral Response: { "paths": ["README.md", "src/index.js", ...], "ref": "main" }

GET /repos/files/metadata — List Files with Git Metadata

curl "$CODE_STORAGE_BASE_URL/repos/files/metadata?ref=main&ephemeral=false" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Params: ref (branch/SHA, falls back to default branch then HEAD then main), ephemeral. This endpoint is unpaginated and returns the full file list in one response. Response: { "files": [{ "path", "mode", "size", "last_commit_sha" }], "commits": { "sha": { "author", "date", "message" } }, "ref": "main" }

GET /repos/file — Get File Content

curl "$CODE_STORAGE_BASE_URL/repos/file?path=src/main.go&ref=main" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Response: raw file bytes (streaming), Content-Type set appropriately.

POST /repos/grep — Search Content (Beta)

curl "$CODE_STORAGE_BASE_URL/repos/grep" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "query": {"pattern": "function.*Error", "case_sensitive": false},
    "file_filters": {"include_globs": ["*.ts"], "exclude_globs": ["node_modules/**"]},
    "context": {"before": 2, "after": 2},
    "limits": {"max_lines": 1000},
    "pagination": {"limit": 100}
  }'

Response: { "matches": [{ "path", "lines": [{ "line_number", "text", "type" }] }], "next_cursor", "has_more" }

POST /repos/archive — Download Archive

curl "$CODE_STORAGE_BASE_URL/repos/archive" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main","include_globs":["src/**"],"exclude_globs":["vendor/**"],"archive":{"prefix":"repo/"}}' \
  -o repo.tar.gz

Response: streaming tar.gz. Headers: Content-Type: application/gzip.

Tags Endpoints (POST/GET/DELETE /repos/tags)

# Create lightweight tag
curl "$CODE_STORAGE_BASE_URL/repos/tags" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"v1.0.0","target":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"}'

# List tags
curl "$CODE_STORAGE_BASE_URL/repos/tags?limit=20&cursor=CURSOR" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

# Delete tag
curl "$CODE_STORAGE_BASE_URL/repos/tags" -X DELETE \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"v1.0.0"}'

Tag names must not start with refs/. target must be a full 40-character lowercase hex commit SHA. Create uses git:write; list uses git:read; delete requires both git:read and git:write. If the repository is synced to GitHub, tag create/delete triggers sync automatically.

Notes Endpoints (POST/GET/DELETE /repos/notes)

All use same endpoint; differentiated by action field.

# Create note
curl "$CODE_STORAGE_BASE_URL/repos/notes" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"sha":"COMMIT_SHA","action":"add","note":"Build passed","author":{"name":"CI","email":"ci@x.com"}}'

# Append to note
curl "$CODE_STORAGE_BASE_URL/repos/notes" -X POST \
  -d '{"sha":"COMMIT_SHA","action":"append","note":"\nDeployed to staging",...}'

# Get note
curl "$CODE_STORAGE_BASE_URL/repos/notes?sha=COMMIT_SHA" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

# Delete note
curl "$CODE_STORAGE_BASE_URL/repos/notes" -X DELETE \
  -d '{"sha":"COMMIT_SHA","action":"remove","author":{...}}'

Response: { "sha", "target_ref": "refs/notes/commits", "new_ref_sha", "result": { "success", "status" } }

POST /repos/pull-upstream — Sync from Upstream

curl "$CODE_STORAGE_BASE_URL/repos/pull-upstream" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Returns 202 Accepted. Sync is async. Only works if repo was created with base_repo. Works for GitHub App sync and generic HTTPS Git Sync providers with stored credentials.

DELETE /repos/base — Detach Upstream

curl "$CODE_STORAGE_BASE_URL/repos/base" -X DELETE \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

Idempotent. Removes the upstream Git Sync link.

── PAGINATION ────────────────────────────────────────────────────────────────

All list endpoints use cursor-based pagination.

# First page
curl "$CODE_STORAGE_BASE_URL/repos/commits?branch=main&limit=20"

# Subsequent pages — use next_cursor from previous response
curl "$CODE_STORAGE_BASE_URL/repos/commits?branch=main&limit=20&cursor=NEXT_CURSOR_VALUE"

Stop when "has_more": false or next_cursor is absent.

── AGENT PROCEDURES (MULTI-STEP RECIPES) ────────────────────────────────────

PROCEDURE 1: New Repository + First Commit

Goal: Create a repo and push initial files via HTTP API (no local git required).

# Step 1 — Mint JWT with repo:write scope for the new repo ID
# (Use SDK or manual JWT generation; set TOKEN env var)
export CODE_STORAGE_TOKEN="$(mint_jwt --repo my-app --scope repo:write)"

# Step 2 — Create the repository
curl "$CODE_STORAGE_BASE_URL/repos" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_branch":"main"}'
# Response: { "repo_id": "my-app", ... }

# Step 3 — Mint JWT with git:write scope for commits
export CODE_STORAGE_TOKEN="$(mint_jwt --repo my-app --scope git:write)"

# Step 4 — Create first commit via NDJSON stream
printf '%s\n%s\n' \
  '{"metadata":{"target_branch":"main","commit_message":"Initial commit","author":{"name":"Agent","email":"agent@x.com"},"files":[{"path":"README.md","operation":"upsert","content_id":"f1"}]}}' \
  '{"blob_chunk":{"content_id":"f1","data":"IyBIZWxsbwp=","eof":true}}' | \
curl "$CODE_STORAGE_BASE_URL/repos/commit-pack" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @-
# Response: { "commit": { "commit_sha": "abc123..." }, "result": { "success": true } }

PROCEDURE 2: Clone Repo into Sandbox (Git)

Goal: Get an authenticated git URL and clone into an ephemeral environment.

# Step 1 — Mint JWT with git:read (or git:write) scope
export CODE_STORAGE_TOKEN="$(mint_jwt --repo my-app --scope git:read --ttl 3600)"

# Step 2 — Build remote URL
REMOTE_URL="https://t:${CODE_STORAGE_TOKEN}@${ORG_NAME}.code.storage/my-app.git"

# Step 3 — Shallow clone (fastest for sandboxes)
git clone --depth 1 --single-branch "$REMOTE_URL" ./repo

# Step 4 — Work, then push (requires git:write JWT in remote URL)
cd repo
git add . && git commit -m "Agent changes"
git push

PROCEDURE 3: Ephemeral Branch Workflow (Preview Environment)

Goal: Create isolated preview branch, work, then promote to persistent branch.

# Step 1 — Create ephemeral commit (sets up ephemeral branch)
printf '%s\n%s\n' \
  '{"metadata":{"target_branch":"preview/pr-42","base_branch":"main","ephemeral":true,"commit_message":"Preview for PR 42","author":{"name":"CI","email":"ci@x.com"},"files":[{"path":"index.html","operation":"upsert","content_id":"h1"}]}}' \
  '{"blob_chunk":{"content_id":"h1","data":"PGgxPlByZXZpZXc8L2gxPg==","eof":true}}' | \
curl "$CODE_STORAGE_BASE_URL/repos/commit-pack" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/x-ndjson" --data-binary @-

# Step 2 — Read files from ephemeral branch
curl "$CODE_STORAGE_BASE_URL/repos/files?ref=preview/pr-42&ephemeral=true" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

# Step 3 — Promote ephemeral branch to persistent (uses createBranch)
curl "$CODE_STORAGE_BASE_URL/repos/branches/create" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_branch":"preview/pr-42","target_branch":"feature/new-ui","base_is_ephemeral":true,"target_is_ephemeral":false}'

PROCEDURE 4: Fork + Customize (Template Pattern)

Goal: Create new project from a template repo, then customize it.

# Step 1 — Mint repo:write JWT for new repo; also need git:read JWT for source
SOURCE_TOKEN="$(mint_jwt --repo templates/starter --scope git:read)"
export CODE_STORAGE_TOKEN="$(mint_jwt --repo users/alice/my-project --scope repo:write)"

# Step 2 — Fork template
curl "$CODE_STORAGE_BASE_URL/repos" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"base_repo\":{\"provider\":\"code.storage\",\"name\":\"templates/starter\",\"operation\":\"fork\",\"ref\":\"main\",\"auth\":{\"token\":\"$SOURCE_TOKEN\"}}}"

# Step 3 — Customize with a commit
export CODE_STORAGE_TOKEN="$(mint_jwt --repo users/alice/my-project --scope git:write)"
printf '%s\n%s\n' \
  '{"metadata":{"target_branch":"main","commit_message":"Initialize project","author":{"name":"System","email":"system@x.com"},"files":[{"path":"README.md","operation":"upsert","content_id":"r1"}]}}' \
  '{"blob_chunk":{"content_id":"r1","data":"IyBNeSBQcm9qZWN0Cg==","eof":true}}' | \
curl "$CODE_STORAGE_BASE_URL/repos/commit-pack" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/x-ndjson" --data-binary @-

PROCEDURE 5: Git Sync Setup

Goal: Create a repo mirrored from GitHub or a generic HTTPS Git provider and keep it in sync.

# Step 1 — Create repo with GitHub base_repo (GitHub App must be installed)
export CODE_STORAGE_TOKEN="$(mint_jwt --repo my-synced-repo --scope repo:write)"
curl "$CODE_STORAGE_BASE_URL/repos" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_branch":"main","base_repo":{"provider":"github","owner":"my-org","name":"my-repo","default_branch":"main"}}'

# Or create with a generic provider, then store credentials.
# Provider values include gitlab, bitbucket, gitea, forgejo, codeberg, sr.ht, and sourcehut.
# For self-hosted remotes, include upstream_host in base_repo.
curl "$CODE_STORAGE_BASE_URL/repos" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_branch":"main","base_repo":{"provider":"gitlab","owner":"my-group","name":"my-repo","default_branch":"main"}}'

curl "$CODE_STORAGE_BASE_URL/repos/git-credentials" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_id":"REPO_ID","username":"git","password":"ACCESS_TOKEN_OR_PASSWORD"}'

# Step 2 — Trigger initial sync from the configured upstream
export CODE_STORAGE_TOKEN="$(mint_jwt --repo my-synced-repo --scope git:write)"
curl "$CODE_STORAGE_BASE_URL/repos/pull-upstream" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"
# Returns 202 — sync is async

# Step 3 — (Optional) Detach if sync no longer needed
curl "$CODE_STORAGE_BASE_URL/repos/base" -X DELETE \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

PROCEDURE 6: Search and Apply Patch

Goal: Find code with grep, generate a diff, apply it as a commit.

# Step 1 — Search for pattern
curl "$CODE_STORAGE_BASE_URL/repos/grep" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main","query":{"pattern":"TODO","case_sensitive":false},"file_filters":{"exclude_globs":["node_modules/**"]}}'

# Step 2 — Generate patch (standard unified diff format)
PATCH_B64=$(echo "$DIFF_TEXT" | base64)

# Step 3 — Apply as commit
printf '%s\n%s\n' \
  '{"metadata":{"target_branch":"main","commit_message":"Fix TODOs","author":{"name":"Agent","email":"agent@x.com"}}}' \
  "{\"diff_chunk\":{\"data\":\"$PATCH_B64\",\"eof\":true}}" | \
curl "$CODE_STORAGE_BASE_URL/repos/diff-commit" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/x-ndjson" --data-binary @-

PROCEDURE 7: Rollback a Branch

Goal: Reset a branch to a known-good commit SHA.

# Step 1 — List commits to find the target SHA
curl "$CODE_STORAGE_BASE_URL/repos/commits?branch=main&limit=20" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN"

# Step 2 — Restore branch to that commit
printf '%s\n' \
  '{"metadata":{"target_branch":"main","target_commit_sha":"GOOD_SHA","author":{"name":"Agent","email":"agent@x.com"},"commit_message":"Rollback to stable"}}' | \
curl "$CODE_STORAGE_BASE_URL/repos/restore-commit" -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/x-ndjson" --data-binary @-

── ERROR HANDLING GUIDE ──────────────────────────────────────────────────────

All API errors return JSON: { "error": "description" } plus HTTP status code. Branch on status codes, not error strings (error strings are not stable).

Specific Scenarios

JWT expired (401):

# Re-mint and retry
export CODE_STORAGE_TOKEN="$(mint_jwt --repo REPO --scope SCOPE --ttl 3600)"
# then retry the original curl

Head SHA mismatch (409 on commit):

# Fetch current HEAD
CURRENT_SHA=$(curl "$CODE_STORAGE_BASE_URL/repos/commits?limit=1" \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" | jq -r '.commits[0].sha')
# Include in next commit attempt as expected_head_sha

Diff cannot be applied (400/result.success=false on diff-commit): Check result.status in response: conflict = merge conflict, precondition_failed = head SHA mismatch, empty diff = no changes. Re-generate the diff against current HEAD.

Empty repo / 404 on file list: Repo exists but has no commits yet. Run PROCEDURE 1 Step 4 to create initial commit.

503 during grep/archive: Repository may be warming up from cold tier storage. Wait 5-10 seconds and retry.

── GIT OPERATIONS REFERENCE ─────────────────────────────────────────────────

# Clone (git:read JWT)
git clone "https://t:${JWT}@${ORG_NAME}.code.storage/${REPO_ID}.git"

# Push (git:write JWT)
git push "https://t:${JWT}@${ORG_NAME}.code.storage/${REPO_ID}.git" main

# Ephemeral remote (insert +ephemeral before .git)
git remote add ephemeral "https://t:${JWT}@${ORG_NAME}.code.storage/${REPO_ID}+ephemeral.git"
git push ephemeral feature-branch

# Promote ephemeral → default
git fetch ephemeral feature-branch:feature-branch
git push origin feature-branch

JWT TTL guidelines:

• CI/CD pipelines: ttl=3600 (1 hour)
• Development environment: ttl=2592000 (30 days)
• Sandbox/ephemeral tasks: ttl=3600 (1 hour)

── KEY CONCEPTS CHEATSHEET ──────────────────────────────────────────────────