diff --git a/playbooks/manage-projects.yaml b/playbooks/manage-projects.yaml
index fb0085f04d..558488c16c 100644
--- a/playbooks/manage-projects.yaml
+++ b/playbooks/manage-projects.yaml
@@ -1,3 +1,23 @@
+# Note that we don't do a sync-project-config before gitea-git-repos
+# because sync-project-config's primary purpose is to update
+# /opt/project-config on the remote host. review.o.o needs this to be
+# updated as jeepyb executes there against the local checkout.
+# gitea-git-repos runs against the project-config on bridge which has
+# already been synced from Zuul to bridge by Zuul.
+#
+# sync-project-config does update project-config from master rather than
+# the Zuul state when run in a periodic or opendev-prod-hourly pipelines
+# but this playbook is never run in those pipelines. It only runs in deploy
+# in response to merged changes.
+#
+# This does mean that we need to be careful landing sequences of changes
+# to rename projects as only the last one in the series should actually
+# run this playbook. Historically, we've avoided problems because Zuul
+# hasn't been able to run post merge jobs at all for intermediate changes
+# after a rename. Only the last change has been in a consistent state
+# which ends up running this playbook. This has mostly been done by chance
+# rather than intentionally and we should take care going forward to not
+# get this wrong.
 - hosts: "gitea:!disabled"
   name: "Create repos on gitea servers"
   roles: