From a8bb35bcc13ee9d0dda9f7dc0902a31c4dab1551 Mon Sep 17 00:00:00 2001
From: "sentry-junior[bot]"
 <264270552+sentry-junior[bot]@users.noreply.github.com>
Date: Fri, 16 Oct 2026 23:47:29 +0000
Subject: [PATCH] docs: refresh docs Co-Authored-By: Joshua Li
 <14209781+joshuarli@users.noreply.github.com>

---
 AGENTS.md | 21 +++++++++++++++++++++
 README.md | 43 +++++++++++++++++++++++++++++++++++++++----
 2 files changed, 60 insertions(+), 4 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1e216bb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,21 @@
+# AGENTS.md
+
+`main.py` mirrors the images pinned in its `IMAGES` tuple from Docker Hub to
+`ghcr.io/getsentry/image-mirror-*`. See [README.md](README.md) for naming and
+the add-an-image workflow.
+
+## Commands
+
+- `python3 main.py update [--dry-run]`: re-resolve every entry's digests and
+  rewrite `IMAGES` in place.
+- `python3 main.py sync [--dry-run]`: push missing digests to ghcr.io. Needs
+  `docker` and a ghcr.io login. CI ([`.github/workflows/main.yml`](.github/workflows/main.yml))
+  runs it.
+- `pre-commit run --files <files>`: lint and format.
+
+## Invariants
+
+- `update` finds `IMAGES` with a regex. Keep `IMAGES = (` and its closing `)`
+  at column 0 with only indented, non-blank lines between them. Otherwise
+  `update` silently writes nothing.
+- Pin digests only for architectures in `ARCHS`.
diff --git a/README.md b/README.md
index e4788b2..cb905f7 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,43 @@
 image-mirror
 ============
 
-to run sentry development we have ~several docker registries -- docker hub
-being the flakiest.
+Sentry development pulls images from several Docker registries, and Docker Hub
+is the flakiest. This repo mirrors pinned Docker Hub images into GitHub's
+registry (ghcr.io) so you have one fewer place to pull from.
 
-this mirrors images from docker hub into github's registry (ghcr) so we have
-one fewer place to pull from
+## Use a mirrored image
+
+Each entry in `IMAGES` in [`main.py`](main.py) is published as:
+
+```
+ghcr.io/getsentry/image-mirror-<source with "/" replaced by "-">:<tag>
+```
+
+For example, `library/postgres` tag `14-alpine` is
+`ghcr.io/getsentry/image-mirror-library-postgres:14-alpine`.
+
+Only the pinned `amd64` and `arm64` digests are mirrored.
+
+## Add or update an image
+
+1. Add an `Image(registry=..., source=..., tag=...)` entry to `IMAGES` in
+   `main.py`.
+2. Run `python3 main.py update` to fill in the digests and sort the list.
+3. Open a pull request.
+
+`update` re-resolves the digests of every entry, not only the new one. Entries
+with mutable tags, such as `latest` or `14`, pick up new digests. Run
+`python3 main.py update --dry-run` to print the rewritten file without saving
+it.
+
+`update` fails with HTTP 400 when it reaches a single-architecture entry, such
+as `checkr/flagr:latest`. Until that is fixed, add the new entry's digests by
+hand. Get them with `docker buildx imagetools inspect <image>:<tag>`.
+
+CI runs `python3 main.py sync --dry-run` on pull requests to list the images it
+would push. After merge, CI runs `sync` on `main` and pushes each image that is
+missing one of its pinned digests on ghcr.io.
+
+## License
+
+See [LICENSE](LICENSE).