docs: refresh docs

[sentry-junior]

Scope: whole repo, no audience filter; part of a devinfra docs refresh.

The only doc was an 8-line README that said what the repo is but not how to use a mirrored image or add one. This PR adds that coverage. Markdown went from 8 lines to 64 lines, a net increase for new coverage.

Files

• README.md (rewritten): purpose, the published image name for each entry, the add-or-update workflow, what CI does on PRs and on main, and the license. Nothing was cut except informal wording.
• AGENTS.md (created): a thin router with the commands, two invariants, and a pointer to the README.
• No source files changed. The comments in main.py are an external-quirk note about docker.io and tool-required # noqa: E501, so all of them stay.

Claims and code evidence

• Image name ghcr.io/getsentry/image-mirror-<source with / replaced by ->:<tag>: dest_img in main() sync.
• Only amd64 and arm64 are mirrored: the ARCHS filter in Image.update.
• update re-resolves every entry, including mutable tags: it loops over all of IMAGES. PR chore(pg): Add v18 postgres and run update #32 hit this.
• CI runs sync --dry-run on PRs and sync after docker login ghcr.io on pushes to main: .github/workflows/main.yml.
• sync re-pushes all digests of an image when any one is missing: it computes todo but then loops over img.digests.
• update silently does nothing when the IMAGES block does not match its regex, because re.sub with no match returns the source unchanged.

Could not verify

• Whether new ghcr.io packages are public by default, and who can change that. Not documented.
• The pre-commit hooks were not run. See checks.

Code looks wrong (not changed)

• update crashes with HTTP 400 on single-architecture images. Reproduced on checkr/flagr:latest. In _digests, for the SINGLE content type, the blob request sends Authorization: Bearer. Docker Hub redirects to a presigned S3 URL, urllib forwards the header, and S3 rejects the doubled auth. Suggested fix: fetch the blob without following the redirect automatically, then re-request the Location without the header. The README documents a manual workaround until this is fixed.
• ARCHS contains 'arm64/v8', but _digests returns only platform['architecture'] with no variant, so that entry never matches. It is dead, and harmless.
• update exits 0 without writing anything when the regex misses (see above). Raising when there is no match would enforce the AGENTS.md invariant.

Candidates to enforce

• The IMAGES block layout invariant: make update fail when the regex does not match.

Skipped

• Nothing. The repo is one script, one workflow, and one README.

Checks run

• python3 main.py --help to confirm the subcommands and --dry-run.
• python3 main.py update --dry-run failed on checkr/flagr:latest. Calling _digests directly reproduced the S3 400. A multi-arch entry (clickhouse/clickhouse-server:26.8.1.2041) resolved to the pinned digests.
• Every Markdown link target in the changed files exists (test -e).
• I checked by hand for trailing whitespace and the final newline. pre-commit was not available in the sandbox (no pip), so I did not run the repo hooks.

via @joshuarli.

--

View Junior Session [Sentry]