diff --git a/.gitea/workflows/container.yml b/.gitea/workflows/container.yml
index df4a1fd..1da3dc5 100644
--- a/.gitea/workflows/container.yml
+++ b/.gitea/workflows/container.yml
@@ -48,13 +48,26 @@ jobs:
 
       - uses: docker/setup-buildx-action@v3
 
+      # Gitea job tokens (GITEA_TOKEN / github.token) cannot log into the
+      # container registry. A PAT with package read/write is required.
+      # https://docs.gitea.com/usage/actions/comparison
+      - name: Require registry PAT
+        if: github.event_name != 'pull_request'
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          if [ -z "$REGISTRY_TOKEN" ]; then
+            echo "::error::Add a Gitea PAT with package read/write as the REGISTRY_TOKEN secret (repo or org). Job tokens cannot authenticate to https://${REGISTRY}/v2/."
+            exit 1
+          fi
+
       - name: Log in to the Gitea Container Registry
         if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ secrets.REGISTRY_USERNAME || github.actor }}
-          password: ${{ secrets.REGISTRY_TOKEN || secrets.GITEA_TOKEN }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
 
       - name: Build and push
         uses: docker/bake-action@v6
diff --git a/README.md b/README.md
index 10b260d..db2fd97 100644
--- a/README.md
+++ b/README.md
@@ -66,19 +66,19 @@ Pull requests **build** the images but do **not** push.
 3. Register an **act_runner** that can build images: Docker socket or privileged `dind`. A label matching `runs-on: ubuntu-latest` is enough.
 4. If `actions/checkout@v4` and the Docker actions cannot be fetched, either set Gitea `[actions].DEFAULT_ACTIONS_URL = github` or mirror those actions onto this instance and change the `uses:` lines.
 
-The workflow logs in as the user who triggered the job (`github.actor`) with `secrets.GITEA_TOKEN`. Give that token **package write** if the instance uses restricted token permissions.
-
-If login returns **401**, create a PAT with **package read/write** and add repository secrets:
+Gitea job tokens (`GITEA_TOKEN`) **cannot** log into the container registry. Create a [personal access token](https://docs.gitea.com/development/api-usage#authentication) with **package read and write** (and **repository read** if the images are private) and add it as a secret on this repo or the `AtlasHorizon` org:
 
 | Secret | Purpose |
 | --- | --- |
-| `REGISTRY_TOKEN` | PAT used instead of `GITEA_TOKEN` |
-| `REGISTRY_USERNAME` | Optional; defaults to the triggering user |
+| `REGISTRY_TOKEN` | Required. PAT used for `docker login` |
+| `REGISTRY_USERNAME` | User that owns the PAT. Set this if it is not the user who triggered the workflow |
 
 | Variable | Purpose |
 | --- | --- |
 | `REGISTRY` | Registry host if it is not the Gitea web hostname |
 
+A `Get "https://git.atlashorizon.net/v2/": unauthorized` failure means the PAT is missing, has the wrong scopes, or `REGISTRY_USERNAME` does not match the token owner. Copying `REGISTRY_TOKEN` from another repo (for example cert-portal) onto this org/repo is enough if that token already works.
+
 ```bash
 docker login git.atlashorizon.net
 docker pull git.atlashorizon.net/atlashorizon/container-base/debian-slim:trixie