Repositories live at /api/v1/repos, declared as an Effect HttpApi.
One schema types the server, the client, and your tests:
import { GitApi } from "@alchemy.run/git";
import * as HttpApiClient from "effect/http-api/HttpApiClient";
const client = yield* HttpApiClient.make(GitApi, { baseUrl: host });
const created = yield* client.repos.create({
payload: { owner: "acme", name: "web", public: true },
}); Everything below is also plain HTTP for curl and fetch, and the
GitHub facade covers Octokit.
Creating
yield* client.repos.create({
payload: {
owner: "acme",
name: "web",
description: "the marketing site",
defaultBranch: "main", // default
public: true, // default false
readOnly: false,
},
}); The response carries the repository and its clone URL. A duplicate
owner/name is a typed RepoAlreadyExists. Who may create under an
owner is your middleware's call; the engine attaches no meaning to the
owner name beyond uniqueness.
owner/name is the public identity. The repository's id is stable, so
renaming never moves data.
Visibility
public is a flag the engine stores and reports. What it grants is
your middleware's decision; the tutorial's middleware serves anonymous
reads of a public repository, REST reads, raw files, the ref
advertisement, and upload-pack, and answers 401 with
WWW-Authenticate otherwise, so git prompts. Git.isRead and
Git.RegistryStore are what it asks.
Listings return everything the Registry holds; public: true in the
query narrows them to public repositories.
Read-only
readOnly: true rejects pushes in-band, so the client sees a clear
error on the ref rather than a transport failure. Use it to freeze a
migrated repository or park one you are retiring.
Updating
yield* client.repos.update({
params: { owner: "acme", repo: "web" },
payload: { description: "archived", readOnly: true },
}); defaultBranch must name a branch that exists. Pointing it at a
missing ref is a typed RefNotFound.
Forking and importing
Fork copies a repository server-side, with no round trip through a client:
yield* client.repos.fork({
params: { owner: "acme", repo: "web" },
payload: { targetOwner: "dana", targetName: "web" },
}); Import pulls from any public git URL. Both return at once with
status: "importing". Poll repos.get until it reads "ready".
Deleting
yield* client.repos.delete({ params: { owner: "acme", repo: "web" } }); Delete answers 204 at once and purges in the background. The name is
released and the objects drain through a scheduled job. A second
delete during the drain is an idempotent 204, and reads of a
draining repository behave as if it were gone.
Listing
const page = yield* client.repos.list({ query: { owner: "acme" } }); Paginated with an opaque cursor. Listings come from the registry, so object counts read as zero here. Fetch a repository directly for live numbers.