.gitea/workflows/ci-images.yml

@@ -62,9 +62,11 @@ jobs:
           fi
           docker version --format 'client {{.Client.Version}} / server {{.Server.Version}} / arch {{.Server.Arch}}'
 
-      # secrets.GITHUB_TOKEN is the Actions task token and can write packages
-      # for the repository owner. REGISTRY_TOKEN is an escape hatch: set it to
-      # a PAT with package:write if the task token is ever refused.
+      # REGISTRY_TOKEN (org secret, a PAT with the package scope) is what
+      # actually works. Gitea's Actions task token is rejected by the
+      # container registry — go-gitea/gitea#23642 — so the GITHUB_TOKEN
+      # fallback below only exists to keep this readable on an instance where
+      # that is ever fixed. See docs/ci.md.
       - name: Log in to the container registry
         if: github.event_name != 'pull_request'
         run: |

docs/ci.md

@@ -66,9 +66,17 @@ one of a different architecture ever joins, it will overwrite these tags with
 its own arch and the rest will fail to pull — at which point the build needs
 `docker buildx` and a multi-arch manifest.
 
-## If a push is refused
+## Registry authentication
 
-The build authenticates with `secrets.GITHUB_TOKEN`, the Actions task token.
-If the registry ever refuses it, create a personal access token with
-`package:write`, store it as the `REGISTRY_TOKEN` secret, and optionally set
-the `REGISTRY_USER` variable — the workflow prefers both when present.
+The build pushes with the `REGISTRY_TOKEN` secret, set at the organisation
+level. **This is required, not optional.** Gitea's Actions task token
+(`secrets.GITHUB_TOKEN`) is rejected by the container registry —
+`docker login` fails with `Get "https://git.unsupervised.ca/v2/":
+unauthorized`. That is [go-gitea/gitea#23642][], open since 2023.
+
+`REGISTRY_TOKEN` is a personal access token with the `package` scope, Read
+and Write. The workflow logs in as `github.actor`, which must be the account
+that owns the token; if it ever needs to differ, set a `REGISTRY_USER`
+variable and the workflow will prefer it.
+
+[go-gitea/gitea#23642]: https://github.com/go-gitea/gitea/issues/23642