diff --git a/.gitea/workflows/docker-publish.yml b/.gitea/workflows/docker-publish.yml
index 3873f44..b07e8be 100644
--- a/.gitea/workflows/docker-publish.yml
+++ b/.gitea/workflows/docker-publish.yml
@@ -37,18 +37,21 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      # Log into the Gitea Container Registry except on PR. The automatic
-      # Actions token can push packages owned by the same user/org. If package
-      # publishing is restricted on your instance, create a personal access
-      # token with the "write:package" scope and store it as the PACKAGES_TOKEN
-      # secret, then swap the password below to ${{ secrets.PACKAGES_TOKEN }}.
+      # Log into the Gitea Container Registry except on PR.
+      #
+      # NOTE: Gitea's automatic Actions token (secrets.GITHUB_TOKEN) is NOT
+      # granted package scope, so it cannot push to the container registry.
+      # Create a Gitea personal access token with the "write:package" scope
+      # (Settings -> Applications -> Access Tokens) and add it as a repo/org
+      # Actions secret named PACKAGES_TOKEN. Set PACKAGES_USER to the token
+      # owner's username (defaults to the triggering actor).
       - name: Log into registry ${{ env.REGISTRY }}
         if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+          username: ${{ vars.PACKAGES_USER || github.actor }}
+          password: ${{ secrets.PACKAGES_TOKEN }}
 
       # Extract metadata (tags, labels) for Docker.
       - name: Extract Docker metadata