diff --git a/.gitea/workflows/coder-templates.yml b/.gitea/workflows/coder-templates.yml
index 7ee55fa..29c0a9d 100644
--- a/.gitea/workflows/coder-templates.yml
+++ b/.gitea/workflows/coder-templates.yml
@@ -20,6 +20,13 @@ name: Provision Coder Templates
 # `permissions: packages: write` below. See
 # https://docs.gitea.com/usage/actions/token-permissions/
 #
+# GITEA_TOKEN impersonates whoever authenticated the triggering push
+# (github.actor), not necessarily the repo owner - that account needs
+# write access to this repo's package registry itself, separate from
+# having git push access to the repo. A push authenticated as an account
+# without registry access fails at docker login with a plain
+# "unauthorized" (not a token/config problem).
+#
 # Any templates/<env>/ that has its own Dockerfile gets its image built and
 # pushed here (build-images, on the dedicated "docker-build" runner - see
 # templates/web/main.tf for why: that runner is scoped to this repo only and