diff --git a/.gitea/workflows/build-server.yml b/.gitea/workflows/build-server.yml
index 5007012..db7c85e 100644
--- a/.gitea/workflows/build-server.yml
+++ b/.gitea/workflows/build-server.yml
@@ -9,8 +9,13 @@
 # Tags are namespaced (server-v1.2.3) so app releases (v*) and server
 # releases don't trigger each other's pipelines.
 #
-# Required secrets: none beyond the built-in GITHUB_TOKEN — it can push to
-# the registry of its own repo and create releases.
+# Required secrets:
+#   REGISTRY_TOKEN  personal access token with read+write package scope —
+#                   the built-in Actions token is NOT accepted by the
+#                   container registry (docker login → unauthorized).
+#                   Create: user Settings → Applications → Generate token.
+#   REGISTRY_USER   optional; defaults to the pushing actor's username.
+# The release job needs only the built-in GITHUB_TOKEN.
 
 name: server-release
 on:
@@ -79,9 +84,13 @@ jobs:
           echo "image=$HOST/${GITHUB_REPOSITORY,,}-server" >> "$GITHUB_OUTPUT"
 
       - name: Build + push image (needs a Docker-capable runner)
+        env:
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER || github.actor }}
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
         run: |
           command -v docker >/dev/null || { echo "::error::no docker on this runner — image skipped; binaries/release are unaffected"; exit 1; }
-          echo "${{ secrets.GITHUB_TOKEN }}" | docker login "${{ steps.meta.outputs.host }}" -u "$GITHUB_ACTOR" --password-stdin
+          [ -n "$REGISTRY_TOKEN" ] || { echo "::error::secret REGISTRY_TOKEN missing — the registry rejects the built-in Actions token. Create a PAT with package read/write scope and add it under Settings → Actions → Secrets."; exit 1; }
+          echo "$REGISTRY_TOKEN" | docker login "${{ steps.meta.outputs.host }}" -u "$REGISTRY_USER" --password-stdin
           docker build server \
             --build-arg VERSION=${{ steps.meta.outputs.version }} \
             -t "${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.version }}" \