How it works

Amendable is Git storage, not a full GitHub replacement. There is no pull-request product, no hosted Actions, and no social graph. You get private repositories, an HTTP API, HTTPS Git, a simple browse UI, and webhooks.

Agents and apps talk to Git HTTPS and the REST API. Objects live in platform S3 or a customer bucket.

Two protocols

Protocol	Host	Auth	What it is for
REST API	`https://api.amendable.io`	Header `access-token`	Create repos, tokens, webhooks, BYO buckets, usage
Git Smart HTTP	`https://amendable.io`	HTTP Basic, password = token	`git clone`, `fetch`, `push`

The browse UI is also on https://amendable.io/r/<user>/<repo>. It is for humans. Agents should prefer Git and the API.

Git HTTPS Basic auth uses the Amendable username and the access token as the password.

Repository lifecycle

POST /v1/repositories creates a private repo and an empty Git store.
First git push creates the default branch (whatever you pushed).
Later pushes add commits. Amendable stores Git objects as layer tarballs in S3.
DELETE /v1/repos/{user}/{name} removes the repo. HTTP 204.

Layer storage is chosen at create time:

Bound BYO bucket, if you pass storage_bucket_id and that bucket is ACTIVE
Otherwise the account default ACTIVE BYO bucket
Otherwise Amendable platform storage

You cannot move a repo to a different bucket later. Delete and recreate if you must change storage.

Access tokens

A token has:

Scope: ALL_REPO or SELECTED_REPO
Grants: which operations it may perform
Optional expires_at

ALL is a shortcut that covers every grant. GIT_HTTP_WRITE always includes GIT_HTTP_READ (the API adds read for you).

The web UI defaults to Grant All Permissions. That is the right choice for a laptop or an agent doing setup. For CI, mint a narrower token or use OIDC for machines.

Details: Grants and scopes.

Webhooks

Webhooks are account-level. One endpoint receives events from every repository you own. Events: push, create, delete, ping (repository is reserved).

Each delivery is JSON plus:

X-Amendable-Event
X-Amendable-Event-Id
X-Amendable-Delivery
X-Amendable-Signature (hex HMAC-SHA256 of the raw body)

Identity for machines

Two different OIDC stories. Do not mix them.

Feature	Issuer	Audience	Result
Machines talking to Amendable	GitHub, GitLab, your IdP	`amendable:<your user uuid>`	Short-lived access token from `POST /v1/oidc/token`
Amendable talking to your S3	`https://oidc.amendable.io`	`amendable-byo-storage`	STS AssumeRoleWithWebIdentity into your IAM role

Quotas

Free: 5 active repos, 1 GiB stored, 5 GiB transfer per UTC month. Paid plans raise those numbers and add metered overage. BYO S3 is Pro and Platform only.

See Usage and quotas.