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. Amendable notifies your HTTPS webhook endpoint when refs change.

Two protocols

Protocol	Host	Auth	What it is for
REST API	`https://api.amendable.io`	`Authorization: Bearer`	Create repos, tokens, webhooks, BYO buckets, usage; list trees and fetch files
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 uses the website session, so it is for the Amendable account owner. Agents should prefer Git and the API.

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.

Layers

Git on Amendable is not a sticky disk volume. Each push is an overlayfs diff packed as {prefix}layers/{layer-id}.tar.gz in S3 (platform or BYO). Older layers are the read-only lower dirs. The new layer is the writable upper dir (only what changed). Snapshots flatten the chain every 10 layers so mounts stay short. See the stack diagram on Bring your own S3. Your Git client still talks only to https://amendable.io. Amendable reads and writes the objects. The design write-up is How BeanHub works: layer-based Git repos.

Auditable history

Git commit graphs are mutable. A force-push can rewrite git log and hide what used to be on the branch. Amendable still records that push as a new immutable layer. Earlier layers stay. Each layer is the overlayfs diff of that push: the files that changed, including Git objects and refs.

That is the audit trail. You can still see who changed the repository, and how, even when Git history was rewritten. Clones serve the current tip. The layer chain is the record of every push that produced it. See How Git is stored.

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). See Webhooks.

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. Pro raises those numbers and adds metered overage. Pro active repositories are unlimited for typical use, with a default ceiling we can raise. BYO S3 is a Pro feature. Enterprise is custom: email support@amendable.io.

See Usage and quotas.