Skip to main content

​
Installation & Setup

pnpm i @pierre/storage
Initialize the client: 
import { GitStorage } from "@pierre/storage";

const store = new GitStorage({
  name: "your-org", // Your organization identifier
  key: env.privateKey,
});
Need to generate JWTs yourself? See Authentication & security → Manual JWT generation.

​
Error Handling

The SDK surfaces API failures as ApiError and ref update failures as RefUpdateError. 
import { ApiError, RefUpdateError, GitStorage } from "@pierre/storage";

const store = new GitStorage({ name: "your-name", key: env.privateKey });

try {
  const repo = await store.createRepo({ id: "existing" });
  console.log(repo.id);
} catch (err) {
  if (err instanceof ApiError) {
    console.error("API error:", err.message);
    console.error("Status code:", err.statusCode);
  } else {
    throw err;
  }
}

const repo = await store.findOne({ id: "repo-id" });
const builder = repo?.createCommit({
  targetBranch: "main",
  commitMessage: "Update docs",
  author: { name: "Docs Bot", email: "docs@example.com" },
});

try {
  const result = await builder
    ?.addFileFromString("docs/changelog.md", "# v2.0.1\n- add streaming SDK\n")
    .send();
  console.log(result?.commitSha);
} catch (err) {
  if (err instanceof RefUpdateError) {
    console.error("Ref update failed:", err.message);
    console.error("Status:", err.status);
    console.error("Reason:", err.reason);
    console.error("Ref update:", err.refUpdate);
  } else {
    throw err;
  }
}

​
Repository Properties

Once you have a repository instance from createRepo() or findOne(), these properties are available:
PropertyTypeDescription
idstringThe repository identifier
defaultBranch (TypeScript)
default_branch (Python)		stringThe repository’s default branch name (e.g., main)
const repo = await store.findOne({ id: "my-repo" });
console.log(repo.id); // 'my-repo'
console.log(repo.defaultBranch); // 'main'

​
Complete Example

import { GitStorage } from "@pierre/storage";

const store = new GitStorage({
  name,
  key: process.env.PIERRE_PRIVATE_KEY,
});

async function setupRepository() {
  // Create repository
  const repo = await store.createRepo({
    id: "backend/api-service",
  });

  // Generate secure URL
  const url = await repo.getRemoteURL({
    permissions: ["git:read", "git:write"],
    ttl: 31536000, // 1 year
  });

  // Use with Git
  console.log(`git clone ${url}`);

  return repo;
}