diff --git a/.gitea/workflows/build.yml b/.gitea/workflows/build.yml
index 60c9311..3081a91 100644
--- a/.gitea/workflows/build.yml
+++ b/.gitea/workflows/build.yml
@@ -19,8 +19,11 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Log in to Gitea registry
+        # The auto-generated secrets.GITEA_TOKEN doesn't work against the registry's
+        # /v2/ auth endpoint regardless of permissions granted (known Gitea limitation);
+        # a real personal access token stored as REGISTRY_TOKEN is required instead.
         run: |
-          echo "${{ secrets.GITEA_TOKEN }}" | docker login "${{ vars.REGISTRY_HOST }}" \
+          echo "${{ secrets.REGISTRY_TOKEN }}" | docker login "${{ vars.REGISTRY_HOST }}" \
             -u "${{ gitea.actor }}" --password-stdin
 
       - name: Build and push claude-agent image