Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

amber-git

Beta Base URL: https://amber-git.stackwell.tech

Overview

amber-git is a git server you can give an AI agent push access to without risking your history. You use it with stock git over HTTPS. The difference is in what a push may do:

  • Adding is free. Creating a branch or tag and fast-forwarding a branch apply at once, as on any git server. A tag, once pushed, doesn’t move.
  • Losing history needs approval. A force-push or a branch or tag delete is not applied when you push it. amber-git refuses it with a handle, files it with Granite for the repository’s owner, and applies it only if the owner approves and the branch has not moved since.
  • Nothing pushed is deleted. The objects you push are stored append-only.
  • Some default branches need green CI. In a repository set up for it, a push that moves the default branch is refused until the commit’s required CI checks have passed.

Every request needs a ChirpAuth token, and every repository is closed until Stackwell grants you access to it.

It is for developers whose agents push code, and for anyone who wants a person’s approval to stand between a mistaken git push --force and lost work.

What beta means here: amber-git runs in production, and Stackwell’s own repositories live on it. Stackwell creates repositories and grants access; there is no self-serve sign-up and no web interface. Some protections are not finished; Concepts and Data and privacy mark each one “Not yet”.

Quickstart

1. Check that amber-git is reachable

No credentials needed:

curl -fsS https://amber-git.stackwell.tech/health

ok

2. Get access

Stackwell registers your ChirpAuth client with amber-git and grants it access to the repositories you need. Repositories are at https://amber-git.stackwell.tech/<repo>.git.

3. Get a token

Exchange your client’s id and secret for a ChirpAuth machine token:

TOKEN=$(curl -sS https://signin.chirpauth.com/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" | jq -r .id_token)

4. Clone and push

Pass the token as a header:

git -c http.extraHeader="Authorization: Bearer $TOKEN" \
  clone https://amber-git.stackwell.tech/myrepo.git

Or give it to git as the password, with any username, through a credential helper; see Authentication. Pushes that add history work as usual:

git push origin my-branch

5. Force-push, and wait for approval

A force-push is refused and queued:

$ git push --force origin main
To https://amber-git.stackwell.tech/myrepo.git
 ! [remote rejected] main -> main (queued for approval by the repo owner (ref VTvpvFgh_qVc))
error: failed to push some refs to 'https://amber-git.stackwell.tech/myrepo.git'

VTvpvFgh_qVc is the handle for your queued force-push. The repository’s owner sees the request in Granite. If they approve it, amber-git moves main to your commit; run git fetch to see it. If you change your mind first, withdraw it:

curl -sS https://amber-git.stackwell.tech/myrepo.git/withdraw \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"handle": "VTvpvFgh_qVc"}'

withdrawn: VTvpvFgh_qVc will never apply

Authentication

Every request except /health needs a ChirpAuth ID token, sent as a bearer token or as the password of HTTP Basic auth. Agents and services use a machine token from a ChirpAuth client that Stackwell has registered with amber-git. Each repository admits only the people and clients Stackwell has granted. Authentication has the details and a table of who may do what.

API reference

amber-git speaks git’s smart HTTP protocol, so git is the main client. Next to it are four small HTTP routes: withdraw a queued push, check whether one is still waiting, re-send a repository to its GitHub mirror, and read a commit’s files without cloning. API examples covers each with real requests and responses, and Concepts explains the rules they follow. The generated API reference can’t list amber-git’s routes yet.

Conventions:

  • Base URL https://amber-git.stackwell.tech. A repository is /<repo>.git.
  • Responses other than git’s own are plain text, except where a route returns file bytes.

Errors and limits

git shows a refused ref update as ! [remote rejected] <ref> (<reason>). Other errors are HTTP statuses with a plain-text body: 401 without a valid token, 403 or 404 when you can’t reach a repository, 410 for a repository that was renamed or retired, 413 past a size limit, and 503 with Retry-After when the server is busy. A push may carry up to 2 GiB. Errors and limits lists every status and limit.

Data and privacy

amber-git keeps every object you push, including those of pushes it refuses, and never deletes them. It logs who pushed what. Queued force-pushes and deletes are sent to Granite with who requested them, and repositories set up to mirror are copied to GitHub. Data and privacy says exactly what is stored, where, and what deleting does and does not do.