Skip to main content

​
Repository management

Code Storage repositories are identified by unique IDs. You can either let the system generate an ID or provide your own: 
// Auto-generated ID
const repo = await store.createRepo();
console.log(repo.id); // e.g., '123e4567-e89b-12d3-a456-426614174000'

// Custom ID with namespacing
const customRepo = await store.createRepo({ id: 'team/project-alpha' });
console.log(customRepo.id); // 'team/project-alpha'
Repository names can include / for organizing repositories by team, project, or user.

​
Authentication & Security

All access to Code Storage requires JWT tokens signed by your organization. Each token:
  • Grants access to a single repository
  • Contains explicit permission scopes
  • Has a configurable time-to-live (TTL)
  • Is customer-signed for full control
The SDK helps simplify and automate the management of these tokens.

​
Token structure

{
  "iss": "your-org", // Your organization identifier
  "sub": "ci-pipeline-prod", // Agent identity (for logging)
  "repo": "team/project-alpha", // Repository access
  "scopes": ["git:read", "git:write"], // Permissions
  "iat": 1723453189, // Issued at (Unix timestamp)
  "exp": 1723456789 // Expiration (Unix timestamp)
}
SDK note: the client normalizes Git status codes in state to descriptive values and provides the original status under rawState alongside camelCase property names.
JWT headers must include: 
{
  "alg": "ES256", // Algorithm (ECDSA with P-256 curve)
  "typ": "JWT", // Type
  "kid": "key-2024-01" // Key ID for rotation
}

​
Permission scopes

ScopeDescriptionOperations
git:readRead repository contentsclone, fetch, pull
git:writeModify repositorypush (includes read)
repo:writeCreate repositoriesPOST /api/v1/repos
git:writeSync from upstreamPOST /api/v1/repos/pull-upstream

​
Key management

Public keys for JWT verification are managed through the Pierre Admin Panel. The kid (Key ID) header enables zero-downtime key rotation—register new keys before retiring old ones. For detailed authentication setup, manual JWT generation, and advanced token configuration, see Authentication.