familienarchiv/docs/adr/029-composite-actions-for-cross-workflow-deploy-logic.md

ADR-029: Composite actions for cross-workflow deploy logic

Status

Accepted

Context

The nightly.yml (staging) and release.yml (production) workflows shared three blocks of deploy logic verbatim: the four observability-stack steps (deploy configs, validate, start, assert health), the Caddy reload step, and the public-surface smoke test. The only per-environment differences were secret names (STAGING_* vs PROD_*), the POSTGRES_HOST value, and the smoke-test hostname.

This duplication was held together by # Keep in sync with nightly.yml comments — an honour-system invariant. Any change (a new healthchecked service, a different rsync flag, a new secret) had to be applied in two places, and nothing enforced that it was. Issue #603 documents a real instance: the obs secret set had grown to five keys while a refactor draft listed only four.

Decision drivers

1. Cross-workflow deploy logic must have a single definition, enforced — not a discipline-based "keep in sync" promise.
2. Per-environment variation must be expressed as explicit, typed inputs, not by forking the whole step block.
3. The mechanism must work on the existing single-tenant self-hosted Gitea runner with no new infrastructure.

Alternatives considered

A: Reusable workflow (workflow_call) — Gitea supports called workflows. Rejected for this case: reusable workflows run as a separate job with their own runner context, which breaks the in-job, sequential deploy → reload → smoke ordering these steps rely on and complicates passing the already-checked-out workspace. Composite actions run inline in the calling job, preserving step order and the workspace.

B: Shared shell script invoked from both workflows — e.g. scripts/deploy-obs.sh. Rejected: loses the typed-input contract and per-step CI log sections, and reintroduces manual argument threading that is as error-prone as the duplication it replaces.

C: Keep the # Keep in sync comments — status quo. Rejected: unenforced; issue #603 is direct evidence it fails.

Decision

Extract the shared logic into three single-responsibility Gitea composite actions under .gitea/actions/: deploy-obs (five inputs), reload-caddy (no inputs), and smoke-test (host input). Both workflows invoke each via a single uses: ./.gitea/actions/<name> call, passing per-environment values as with: inputs. This is the repository's first composite action and sets the convention; docs/infrastructure/ci-gitea.md documents it.

Consequences

Positive:

• Shared deploy logic has one enforced definition; a change lands once and both environments get it. The # Keep in sync comments are deleted.
• Per-environment variation is a typed input contract, not a forked block.
• Runs inline on the existing runner — no reusable-workflow job context, no new infrastructure.

Negative / constraints:

• Workflows now depend on a checked-out .gitea/actions/ tree: actions/checkout MUST run before the first uses: ./… (a local action does not exist on disk until checkout).
• Secrets cannot be read from the secrets.* context inside a composite action; they must be passed as inputs and mapped to env:. The obs-secrets.env heredoc therefore uses an unquoted delimiter so $VAR expands at the shell layer.
• The reload-caddy pinned alpine digest now lives in the action, not the workflow file — it must be added to Renovate's watch list so it does not go stale.