.gitea/workflows/nightly.yml

@@ -6,6 +6,18 @@ name: nightly
 # the host daemon and `docker compose up` consumes them directly — no
 # registry hop.
 #
+# Operational assumptions (see docs/DEPLOYMENT.md §3 for the full setup):
+#
+#   1. Single-tenant self-hosted runner. The "Write staging env file" step
+#      writes every secret to .env.staging on the runner filesystem; the
+#      `if: always()` cleanup step removes it. A multi-tenant runner
+#      would need to switch to docker compose --env-file <(stdin) instead.
+#
+#   2. Host docker layer cache is authoritative. There is no
+#      actions/cache; we rely on the host daemon to keep Maven and npm
+#      layers warm between runs. A `docker system prune` on the host
+#      will cause the next nightly build to be cold (5–10 min slower).
+#
 # Staging environment isolation:
 #   - project name: archiv-staging
 #   - host ports:   backend 8081, frontend 3001

.gitea/workflows/release.yml

@@ -5,6 +5,19 @@ name: release
 # tagged with the actual git tag (e.g. v1.0.0) so rollback is
 #   `TAG=<previous> docker compose -f docker-compose.prod.yml -p archiv-production up -d --wait`
 #
+# Operational assumptions (see docs/DEPLOYMENT.md §3 for the full setup):
+#
+#   1. Single-tenant self-hosted runner. The "Write production env file"
+#      step writes every secret to .env.production on the runner
+#      filesystem; the `if: always()` cleanup step removes it. A
+#      multi-tenant runner would need to switch to
+#      `docker compose --env-file <(stdin)` instead.
+#
+#   2. Host docker layer cache is authoritative. There is no
+#      actions/cache; we rely on the host daemon to keep Maven and npm
+#      layers warm between runs. A `docker system prune` on the host
+#      will cause the next release build to be cold (5–10 min slower).
+#
 # Production environment:
 #   - project name: archiv-production
 #   - host ports:   backend 8080, frontend 3000