commit b534ae0d655fb0eda5bc5e24fc119b1ae330e4f7
Author: Alex Maldonado <alex@scient.ing>
Date:   Sun Jul 26 09:40:52 2026 -0400

    initial commit

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..728fd13
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,6 @@
+FROM node:26-trixie-slim@sha256:a1d9d671994fc2d26e297ac56b4b1522a8bc7fa71c43b14cd1b1fe6c5116f7dc
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+     git ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fc0cf31
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# github-readme-sync
+
+The container image the Gitea Actions runner uses to mirror a repository's README to its GitHub pointer.
+
+## What it is
+
+A push that changes `README.md` (or the appended notice) on the Gitea instance triggers a runner to rebuild the combined README and push it to the matching GitHub repository.
+This image is the environment that job runs in.
+
+It is deliberately small.
+The job reads one file, appends a notice, and pushes the result, so the image carries nothing beyond what a checkout and a `git push` need.
+
+Node runs the JavaScript actions Gitea uses to bootstrap a job, such as `actions/checkout`.
+`git` performs the clone, commit, and push, and `ca-certificates` lets it speak HTTPS to GitHub.
+Authentication is a fine-grained access token passed to the job at runtime, so no SSH client or key material lives in the image.
+
+## Build
+
+Build the image on your own machine and push it to Gitea's container registry.
+The runner only ever pulls it.
+
+You will need an access token with `package:write` access, the same kind used for the Quarto image.
+Authenticate Docker with it, then build for `linux/amd64`, since that is what the runner host is and an `arm64` image will push but fail to start with an exec-format error.
+
+```bash
+docker login git.scient.ing
+
+docker buildx build --platform linux/amd64 \
+  -t git.scient.ing/infra/github-readme-sync:1 --push .
+```
+
+Bump the tag with a revision suffix (`:2`, `:3`) whenever the `Dockerfile` changes.
+The image is always pulled by an explicit version, never `latest`, so a runner's behavior stays tied to a named artifact you can roll back to.
+
+## Use
+
+A runner advertises a label that maps to this image, and the sync workflow selects it with `runs-on`.
+
+```yaml
+# in the runner's config.yaml
+runner:
+  labels:
+    - "github-readme-sync:docker://git.scient.ing/infra/github-readme-sync:1"
+```
+
+```yaml
+# in the mirrored repository's .gitea/workflows/sync-readme.yml
+jobs:
+  sync:
+    runs-on: github-readme-sync
+```
+
+The workflow also needs the GitHub token it pushes with, stored as a Gitea Actions secret (`GH_MIRROR_TOKEN`) on the repository or organization, holding a fine-grained PAT scoped to the target GitHub repo with Contents read and write.
+That is repository configuration, not part of this image.
+