github-readme-sync/README.md

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.

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.

# in the runner's config.yaml
runner:
  labels:
    - "github-readme-sync:docker://git.scient.ing/infra/github-readme-sync:1"

# 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.