From 83565c6bb586258da72d57c75eab34afb8dcb1fe Mon Sep 17 00:00:00 2001 From: Marcel Date: Mon, 11 May 2026 12:06:48 +0200 Subject: [PATCH] docs(ci): document workflow operational assumptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two deploy workflows make two non-obvious assumptions that future maintainers should not have to rediscover by reading the diff: 1. Single-tenant self-hosted runner — the .env.* file lands on disk during the deploy and is cleaned up unconditionally. Multi-tenant usage would require switching to stdin-piped env input. 2. Host docker layer cache is authoritative — there is no actions/cache directive; a host-level `docker system prune` will cold-start the next build. Both notes added as block comments at the top of each workflow. Co-Authored-By: Claude Opus 4.7 --- .gitea/workflows/nightly.yml | 12 ++++++++++++ .gitea/workflows/release.yml | 13 +++++++++++++ 2 files changed, 25 insertions(+) diff --git a/.gitea/workflows/nightly.yml b/.gitea/workflows/nightly.yml index bdfa399f..118dd54f 100644 --- a/.gitea/workflows/nightly.yml +++ b/.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 diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index ba5fb168..d4332ba9 100644 --- a/.gitea/workflows/release.yml +++ b/.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= 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