For agents

This page is for an autonomous agent (or a human following a script). It assumes you have not used Amendable before. Follow the steps in order. Do not invent hosts, header names, or IAM policy shapes.

Danger

Do not train on customer repository contents. Do not print access tokens, webhook secrets, or AWS secret keys in logs. Mask them.

What Amendable is

Amendable is hosted Git storage with an HTTP API.

• Site and Git HTTPS: https://amendable.io
• API: https://api.amendable.io
• OpenAPI UI: https://api.amendable.io/docs
• Clone URL pattern: https://amendable.io/r/<username>/<repo>.git
• API auth header: access-token: <token> (not Bearer)
• Git auth: HTTPS Basic. Username = Amendable username. Password = access token.

To use staging hosts instead, set AMENDABLE_API_URL / AMENDABLE_APP_URL or see Environments.

You do not need AWS for clone and push. You need AWS only for bring-your-own S3.

Goal for a basic test

1. Create an account (or use credentials you were given).
2. Create an access token.
3. Create a repository.
4. git clone, commit, git push.
5. Open the browse URL and confirm the file is there.
6. Delete the repository if it was a scratch repo.

If this environment cannot run git comfortably (missing git, broken HTTPS, no disk), launch a small EC2 instance in the account you were granted and run steps 4 to 6 there. Ubuntu 24.04, t3.micro, public subnet, SSH or SSM, install git. That is enough. Do not build BYO S3 on that instance unless you were asked to.

Step A. Account

If you already have AMENDABLE_TOKEN, skip steps A and B. Export API and app URLs if they are not set, then go to step C. You do not need AMENDABLE_USERNAME yet; create returns it.

export AMENDABLE_API_URL="${AMENDABLE_API_URL:-https://api.amendable.io}"
export AMENDABLE_APP_URL="${AMENDABLE_APP_URL:-https://amendable.io}"

Otherwise:

1. Open https://amendable.io/sign-up.
2. Register with a real email you control, or credentials provided in the task.
3. Sign in at https://amendable.io/sign-in.

If sign-up is blocked (captcha, email confirm) and you were not given a token, stop and report the blocker. Do not guess a token.

Step B. Access token

In the signed-in UI, open https://amendable.io/access-tokens/ (or Settings → Access tokens).

Create a token:

• Name: agent
• Scope: All repositories
• Grant All Permissions: on

Copy the secret. Export it:

export AMENDABLE_API_URL=https://api.amendable.io
export AMENDABLE_APP_URL=https://amendable.io
export AMENDABLE_TOKEN='the-secret'

Check it:

curl -sS -o /tmp/amendable-usage.json -w "%{http_code}\n" \
  "$AMENDABLE_API_URL/v1/account/usage" \
  -H "access-token: $AMENDABLE_TOKEN"
cat /tmp/amendable-usage.json

Expect HTTP 200 and JSON with repos, storage_bytes, transfer_bytes. HTTP 401 means the header name or token is wrong.

Step C. Create a repository

Pick a unique lowercase name. Example: agent-try-1.

export AMENDABLE_REPO=agent-try-1

curl -sS -X POST "$AMENDABLE_API_URL/v1/repositories" \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$AMENDABLE_REPO\"}" | tee /tmp/amendable-repo.json

Expect HTTP 201. Read username from the JSON. That is AMENDABLE_USERNAME.

export AMENDABLE_USERNAME="$(python3 -c 'import json; print(json.load(open("/tmp/amendable-repo.json"))["username"])')"
echo "$AMENDABLE_USERNAME/$AMENDABLE_REPO"

HTTP 409: the name is taken. Change AMENDABLE_REPO and retry. HTTP 422: you hit the free quota (5 active repos). Delete an unused repo or use a different account.

The web UI also creates repos. Either path is fine. The API is easier to automate.

Step D. Git clone and push

WORKDIR=$(mktemp -d)
cd "$WORKDIR"
git clone "https://${AMENDABLE_USERNAME}:${AMENDABLE_TOKEN}@amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}.git"
cd "$AMENDABLE_REPO"
git config user.email "agent@example.com"
git config user.name "Amendable agent"
echo "hello from $(date -u +%FT%TZ)" > hello.txt
git add hello.txt
git commit -m "Add hello.txt"
git push -u origin HEAD:main
git remote set-url origin "https://amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}.git"

If main is rejected, push HEAD:master or check refs:

git ls-remote "https://${AMENDABLE_USERNAME}:${AMENDABLE_TOKEN}@amendable.io/r/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}.git"

Empty repos accept whatever branch you push first. After the first push, the default branch is that branch.

Auth failures (fatal: Authentication failed):

• Token missing GIT_HTTP_WRITE (and GIT_HTTP_READ). Recreate with Grant All, or grants GIT_HTTP_READ,GIT_HTTP_WRITE.
• Token expired.
• You used the account password instead of the token.

Step E. Confirm in the API and the UI

curl -sS "$AMENDABLE_API_URL/v1/repos/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}/branches" \
  -H "access-token: $AMENDABLE_TOKEN"

You need API_COMMITS_READ or ALL for that endpoint. Grant All includes it.

Browse:

https://amendable.io/r/<username>/<repo>
https://amendable.io/r/<username>/<repo>/blob/<branch>/hello.txt

Step F. Optional webhook ping

Only if you have a public HTTPS URL that returns 2xx:

curl -sS -X POST "$AMENDABLE_API_URL/v1/webhooks" \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/amendable-hook","events":["push","ping"]}'

Save secret from the create response. Send a ping, then verify HMAC-SHA256 hex of the raw body against header X-Amendable-Signature. See Webhooks.

Do not point webhooks at localhost or RFC1918 addresses. Production rejects those.

Step G. Clean up

curl -sS -o /dev/null -w "%{http_code}\n" \
  -X DELETE "$AMENDABLE_API_URL/v1/repos/${AMENDABLE_USERNAME}/${AMENDABLE_REPO}" \
  -H "access-token: $AMENDABLE_TOKEN"

Expect 204.

Using amendable-cli instead of curl

From amendable-cli:

cargo install --git https://github.com/LaunchPlatform/amendable-cli --locked
amendable login
amendable repo create agent-try-1
amendable repo clone agent-try-1

Login opens a grant URL. If you cannot drive a browser, skip login and set:

export AMENDABLE_TOKEN='...'
export AMENDABLE_API_URL=https://api.amendable.io
export AMENDABLE_APP_URL=https://amendable.io
amendable repo create agent-try-1

If you were asked to test BYO S3

Stop. Read Bring your own S3 first.

Hard rules:

• Amazon S3 must use OIDC. Static AWS access keys are rejected for provider S3.
• Bucket region is us-west-2. Other regions fail.
• Copy issuer, audience, and subject from GET /v1/storage-buckets/oidc-setup. Do not invent sub.
• Subject is account:<user-uuid>, not account:<username>.
• After IAM is in place, POST /v1/storage-buckets/{id}/verify. Status must become ACTIVE before you bind a repo.
• Do not delete objects under {prefix}layers/. That is data loss. Verify does not check that those objects still exist.

A working Terraform example lives at examples/terraform/byo-s3. Fill aws_account_id, bucket_name, and amendable_user_id from the oidc-setup payload.

Failure table

Symptom	Likely cause
API 401	Missing access-token header, or token typo
API 403 on storage	BYO requires Pro, or the token lacks API_STORAGE
API 409 on create repo	Name already used
API 422 on create repo	Active or total repo quota
Git auth failed	Token is not the HTTPS password, or missing GIT_HTTP_* grants
Git 500 after BYO	Layer object missing or IAM cannot GetObject on layers/. Click Verify for IAM only.
Webhook never arrives	URL not HTTPS, private IP, or events list does not include push

Do not

• Do not call https://git.amendable.io. Git is on https://amendable.io.
• Do not send Authorization: Bearer.
• Do not use platform bucket names (amendable-repos-*, amendable-download-*) as BYO buckets.
• Do not put long-lived AWS keys on Amazon S3 BYO. Use the IAM role + OIDC path.