initial commit

2026-07-26 09:40:52 -04:00
commit b534ae0d65
2 changed files with 61 additions and 0 deletions
@@ -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.
+