# Execution Plan — Gitea Deployment Workflow **Feature**: `gitea-deployment-workflow` **Branch**: `feature/gitea-deployment-workflow` **Date**: 2026-07-27 --- ## 1. Detailed Analysis Summary ### Transformation Scope - **Transformation Type**: **Infrastructure and operations transformation with supporting application changes.** This is not a refactor of business logic — it introduces a deployment capability that does not exist today (no `.gitea/` directory) and changes how the application is hosted, configured and observed. - **Primary Changes**: 1. New CI/CD pipeline (two workflow files) where none exists. 2. A change to the hosting contract: the public website moves from `wwwroot/` to `wwwroot/web/`, altering how `Program.cs` serves static content. 3. New cross-cutting application concerns: health checks, HTTP security headers, structured error/log reporting. 4. Durability changes: automatic Core migrations and a database-backed Data Protection key ring. 5. Deployment-model change: from manual publish to an atomic release-directory switch with a retained previous release. - **Related Components**: `SlpModularCms.Api` (`Program.cs`, `.csproj`), `SlpModularCms.Core` (Data Protection, health checks, security headers, logging), `SlpModularCms.Modules.Availability` (bypass list), `frontend/` (config, Sentry, Umami, lint), plus new `.gitea/workflows/` and documentation. - **No infrastructure-as-code exists** (no CDK, Terraform, CloudFormation, Docker). Host setup is documented procedure, not code — a direct consequence of NFR-01 (no server configuration). ### Change Impact Assessment | Area | Impact | Description | |---|---|---| | **User-facing changes** | **Indirect, yes** | No new features for CMS users. But the public website's URL structure is unchanged while its *storage location* changes (`wwwroot/` → `wwwroot/web/`), and a CSP begins applying to pages that previously had none. A too-strict CSP would visibly break a customer website. | | **Structural changes** | **Yes** | Static-file serving is remounted; new middleware enters the pipeline; a new endpoint (`/health`) is added outside `/api/v1`; the availability bypass list grows. | | **Data model changes** | **Yes, additive** | Data Protection key storage moves into the database, requiring a keys table and a `DbContext` implementing `IDataProtectionKeyContext` — a new migration. No existing entity changes. | | **API changes** | **Minimal, additive** | One new non-versioned endpoint `/health`. No change to any `/api/v1` contract. `frontend`'s API base URL becomes same-origin by default, which changes request URLs the SPA emits but not the endpoints themselves. | | **NFR impact** | **Substantial** | Security (headers, CSP, alerting), reliability (atomic switch, rollback, backup), observability (Sentry, Umami, UptimeRobot), and deployment reproducibility are all new or materially changed. This is where most of the feature's substance lives. | ### Component Relationships - **Primary Component**: `SlpModularCms.Api` — the deployable host and the only place where all three surfaces meet. - **Shared Components**: `SlpModularCms.Core` — receives health-check registration, security-headers middleware, Data Protection configuration and logging setup, because both host projects must inherit them. - **Dependent Components**: `SlpModularCms.Api.Slave` — inherits every `Core` change automatically. **It must keep working**, and it is deliberately excluded from deployment (local-only, no test project). - **Modified Module**: `SlpModularCms.Modules.Availability` — `_bypassPrefixes` must include `/health`. - **Frontend Component**: `frontend/` — config, Sentry, Umami, lint fixes. Coupled to the backend at build time through the publish target. - **Supporting Components (new)**: `.gitea/workflows/`, documentation, and external services (Sentry, Umami, UptimeRobot). | Component | Change Type | Change Reason | Priority | |---|---|---|---| | `SlpModularCms.Api` / `Program.cs` | Major | Static-file remount, health endpoint, middleware order, migrations | Critical | | `SlpModularCms.Core` | Minor (additive) | Health checks, security headers, Data Protection, logging | Critical | | `SlpModularCms.Modules.Availability` | Configuration-only | `/health` bypass | Critical | | `SlpModularCms.Api.Slave` | None (inherits) | Must not regress | Important | | `frontend/` | Minor | Same-origin config, Sentry, Umami, lint fixes | Critical | | `.gitea/workflows/` | New | The feature's core deliverable | Critical | | `*.csproj` (packages) | Minor | Pin vulnerable packages, add Sentry / health-check / Data Protection packages | Critical | | Documentation | New + updates | Website contract, README, operations artifacts | Important | ### Risk Assessment - **Risk Level**: **High** - **Rollback Complexity**: **Moderate** - **Testing Complexity**: **Complex** **Why High rather than Medium** — three failure modes are destructive and silent: 1. **Destroying a customer's public website.** An atomic release switch that carries `wwwroot/web/` inside the swapped directory discards the customer's site on every deploy (ASM-01). Data loss, not a bug. 2. **Silently breaking master↔slave trust.** Losing the Data Protection key ring makes stored slave API keys undecryptable. The symptom looks like a network fault, so it would be misdiagnosed. FR-12 prevents it — but only if implemented before the first atomic switch. 3. **Automatic migrations on startup against production.** FR-11 makes deployment self-contained, and consequently makes a bad migration run automatically with no human gate. This is why FR-20 (pre-deploy backup) and forward-compatible migrations are not optional extras. Additional risk factors: the deploy path **cannot be fully tested in CI** — it needs the actual Pi, SSH credentials and a database; and a CSP is a class of change that breaks things only in a real browser, on pages this repository does not own. **Mitigations built into the plan**: durability changes (Unit 2) land *before* any deploy workflow (Unit 6); the CSP starts from a known-origin allowlist with the public website deliberately more permissive (D-31); and quality-gate prerequisites (Unit 1) land first so the blocking gates are meaningful rather than immediately red. --- ## 2. Workflow Visualization ```mermaid flowchart TD Start(["User Request"]) subgraph INCEPTION["🔵 INCEPTION PHASE"] WD["Workspace Detection
COMPLETED"] RE["Reverse Engineering
COMPLETED"] RA["Requirements Analysis
COMPLETED"] US["User Stories
SKIP"] WP["Workflow Planning
IN PROGRESS"] AD["Application Design
EXECUTE"] UG["Units Generation
EXECUTE"] end subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"] FD["Functional Design
EXECUTE per unit"] NFRA["NFR Requirements
SKIP"] NFRD["NFR Design
EXECUTE per unit"] ID["Infrastructure Design
EXECUTE per unit"] CG["Code Generation
Planning plus Generation
EXECUTE"] BT["Build and Test
EXECUTE"] end subgraph OPERATIONS["🟡 OPERATIONS PHASE"] DS["Deployment Setup
EXECUTE"] MS["Monitoring Setup
EXECUTE"] PRV["Production Readiness Validation
EXECUTE"] end Start --> WD WD --> RE RE --> RA RA --> WP WP --> AD AD --> UG UG --> FD FD --> NFRD NFRD --> ID ID --> CG CG --> BT BT --> DS DS --> MS MS --> PRV PRV --> End(["Complete"]) style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style DS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style MS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style PRV fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000 style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000 style OPERATIONS fill:#FFF59D,stroke:#F57F17,stroke-width:3px,color:#000 style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 linkStyle default stroke:#333,stroke-width:2px ``` Text alternative: Inception is complete except Application Design and Units Generation which will execute; User Stories is skipped. Construction runs Functional Design, NFR Design and Infrastructure Design per unit (NFR Requirements skipped), then Code Generation and Build and Test. All three Operations stages execute. --- ## 3. Phases to Execute ### 🔵 INCEPTION PHASE - [x] **Workspace Detection** — COMPLETED - [x] **Reverse Engineering** — COMPLETED (full rerun, all 8 shared artifacts, verified by executing build/test/lint) - [x] **Requirements Analysis** — COMPLETED (23 FRs, 10 NFRs, 32 decisions, 2 question rounds) - [x] **User Stories** — **SKIP** - **Rationale**: This is infrastructure and operations work. It introduces no new end-user functionality, no new persona, and no user journey. The only user-visible effects are a storage-location change and a CSP, both of which are already captured as requirements with acceptance-relevant detail (FR-07, FR-08, FR-18, FR-09). Personas here would be "the developer deploying" and "the website builder consuming the contract" — the latter is properly served by FR-09's documented contract, not by a story. Offered explicitly at Requirements Analysis approval and not requested. - [~] **Workflow Planning** — IN PROGRESS (this document) - [ ] **Application Design** — **EXECUTE** - **Rationale**: New cross-cutting components genuinely need placement decisions that are not obvious. Where do health checks, security headers and Data Protection registration live — `Core` (inherited by both hosts, including the Slave) or `Api` (host-specific)? Getting this wrong either breaks the Slave or duplicates code. Static-file serving must be redesigned for two mounts with two fallbacks and correct ordering relative to the availability gate. The CSP needs a path-scoping mechanism that does not exist yet. And the deploy transport needs an interface that admits FTPS later without restructuring (NFR-09). These are component-boundary and service-layer decisions — exactly this stage's purpose. - [ ] **Units Generation** — **EXECUTE** - **Rationale**: The work spans application code, frontend code, two workflow files, package changes and documentation, with a **mandatory ordering constraint**: durability changes must land before the first automated deploy, and quality-gate fixes must land before blocking gates are switched on. Sequencing this is load-bearing, not bookkeeping. Seven units are proposed in § 5. ### 🟢 CONSTRUCTION PHASE - [ ] **Functional Design** — **EXECUTE for units 2, 3, 4; SKIP for units 1, 5, 6, 7** - **Rationale**: Units 2, 3 and 4 contain real behavioural logic that needs designing before coding — static-file resolution and fallback precedence, migration-at-startup failure behaviour, CSP composition per path, and what a "security-relevant event" is for alerting. Units 1 (lint fixes, package pins), 5 and 6 (declarative YAML) and 7 (documentation) have no business logic to design; a design document there would restate the requirement. - [ ] **NFR Requirements** — **SKIP (all units)** - **Rationale**: NFRs are already captured comprehensively and with traceability in `requirements.md` § 5 (NFR-01…10) and § 6 (full SECURITY-01…15 assessment with four documented deviations). The tech stack is fixed and unchanged. Re-deriving NFRs per unit would duplicate an artifact that already exists at higher quality than a per-unit restatement would produce. - [ ] **NFR Design** — **EXECUTE for units 3 and 4; SKIP for units 1, 2, 5, 6, 7** - **Rationale, including a deliberate deviation**: The workflow's default is that NFR Design is skipped when NFR Requirements is skipped. I am overriding that coupling for two units, because for them the NFR *is* the deliverable: Unit 3 implements SECURITY-04 (how a CSP is composed and path-scoped, how HSTS interacts with the hosting proxy) and Unit 4 implements SECURITY-03 and SECURITY-14 (structured-logging shape, correlation ID per OPEN-01, which events warrant alerting, PII exclusion). Those are pattern decisions, not requirement decisions — so skipping the requirements stage while designing the patterns is the correct split here, not an oversight. For all other units the existing NFRs need no new pattern work. - [ ] **Infrastructure Design** — **EXECUTE for units 6 and 7; SKIP for units 1, 2, 3, 4, 5** - **Rationale**: Unit 6 is where the host layout is decided — release-directory scheme, where `wwwroot/web/` lives so ASM-01 holds, the symlink or mount strategy, process restart, database backup placement, and the transport abstraction. Unit 7's website contract depends on that layout being settled. This is genuine infrastructure design even though it produces documented procedure rather than IaC (NFR-01 forbids server configuration, so there is nothing to codify). Skipped elsewhere: those units change application code and CI definitions, not infrastructure. - [ ] **Code Generation** — **EXECUTE (always, per unit)** - **Rationale**: Implementation planning and code generation are needed for all seven units. Each unit is built and its own tests run before its completion message. - [ ] **Build and Test** — **EXECUTE (always)** - **Rationale**: Full cross-unit build plus everything that only appears once units are combined — middleware ordering with the new security headers and health endpoint, the Slave host still starting correctly, the frontend building against the same-origin config, and the publish target producing the expected `wwwroot` layout. ### 🟡 OPERATIONS PHASE - [ ] **Deployment Setup** — **EXECUTE** - [ ] **Monitoring Setup** — **EXECUTE** - [ ] **Production Readiness Validation** — **EXECUTE** - **Rationale**: `## Operations Configuration` = **Yes**, decided at Requirements Analysis. For this feature Operations is the centre of gravity, not an afterthought: FR-17 (UptimeRobot monitors), FR-19 (Sentry alert rules), FR-20 (pre-deploy database backup) and FR-23 (deployment, host-setup and rollback documentation, including the FTPS switch path) are all delivered here. Production Readiness Validation will also run the `dotnet-appsettings` compliance gate, which is directly relevant given D-16 (host environment variables) and the placeholder values in `appsettings.json`. --- ## 4. Multi-Module Coordination ### Module Update Strategy - **Update Approach**: **Sequential with two parallelisable pairs.** - **Critical Path**: `SlpModularCms.Core` → `SlpModularCms.Api` → `.gitea/workflows/`. Core carries the shared cross-cutting registrations; the Api host composes them and defines serving; the workflows can only deploy something that exists and is durable. - **Coordination Points**: - `Core` ↔ `Api.Slave`: every `Core` change is inherited by the Slave host. The Slave must still start and serve; it has no test project, so this is verified at Build and Test by starting it. - `Core` ↔ `Modules.Availability`: the `/health` bypass must land in the same unit as the health endpoint, or `/health` returns 503 on a disabled instance — the exact conflation the user corrected. - `Api` ↔ `frontend`: coupled bidirectionally — the SPA calls the API at runtime, and the API's publish target builds the SPA. A same-origin config change (Unit 4) and the `wwwroot` remount (Unit 2) must agree on where `/admin` is served from. - Package pinning (Unit 1) touches multiple `.csproj` files and must not conflict with the new packages added in Units 2, 3 and 4. - **Testing Checkpoints**: after each unit (automatic per-unit build + test), plus a full-solution checkpoint at Build and Test that additionally starts both hosts and verifies the publish output layout. - **Rollback Strategy (mid-sequence)**: each unit is a self-contained commit on `feature/gitea-deployment-workflow`. Units 1–4 are revertible independently. Units 5 and 6 add new files only (`.gitea/`) and are revertible by deletion. Nothing is deployed to any environment until Unit 6 is complete and explicitly triggered, so a mid-sequence failure cannot affect a running environment. ### Per-Module Detail | Module | Priority | Depends on | Depended on by | Change Scope | |---|---|---|---|---| | `SlpModularCms.Core` | Must-update-first | — | Both hosts, all modules | Minor (additive) | | `SlpModularCms.Api` | Must-update-first | Core | Deployment | Major | | `SlpModularCms.Modules.Availability` | Must-update-with-Core | Core | Both hosts | Patch (bypass list) | | `SlpModularCms.Api.Slave` | Can-update-later (verify only) | Core | — | None (inherits) | | `frontend` | Must-update-before-CI | Api (same-origin contract) | Api publish target | Minor | | `.gitea/workflows/` | Update-last | Everything above | — | New | | Documentation | Update-last | Infrastructure Design | — | New + updates | --- ## 5. Proposed Unit Sequence Final unit definitions are produced by Units Generation; this is the sequence the plan is built around, with the ordering constraints that make it non-arbitrary. | # | Unit | Delivers | Why here | |---|---|---|---| | 1 | **Quality Gate Prerequisites** | Fix 5 lint errors (FR-21); pin `Microsoft.OpenApi` and `System.Security.Cryptography.Xml` (FR-22) | Blocking gates are switched on in Unit 5. If this does not land first, the pipeline is red on arrival and the gates get disabled "temporarily". Independent of everything else, so it costs nothing to do first. | | 2 | **Hosting Layout & Data Durability** | `wwwroot/web/` remount and dual SPA fallbacks (FR-07, FR-08); `/health` + bypass (FR-10); automatic Core migrations (FR-11); `PersistKeysToDbContext` (FR-12) | Must precede any automated deploy. The key ring and the `wwwroot` split are exactly what make an atomic switch non-destructive; deploying first and fixing after means the first deploy is the dangerous one. | | 3 | **HTTP Security Headers & CSP** | Security-headers middleware, path-scoped CSP (FR-18) | Needs Unit 2's final path layout to scope the CSP. Precedes Unit 4 so the CSP mechanism exists when Umami and Sentry origins need allowing. | | 4 | **Observability Integration** | Sentry backend + frontend (FR-14, FR-15); structured logging (D-20, OPEN-01); Umami (FR-16); same-origin SPA config (FR-13) | Adds the external origins that Unit 3's CSP must permit, and the environment-tagged build variables that Unit 5's two builds must supply. | | 5 | **CI Workflow** | `continuous_integration.yaml`: triggers, six blocking gates, two environment-specific builds, artifacts (FR-01, FR-05) | Gates are meaningful only after Unit 1; the two builds need Unit 4's variables. | | 6 | **Deploy Workflow** | `deploy.yaml`: reusable, transport-abstracted, atomic switch, restart, retained previous release, backup hook (FR-02, FR-03, FR-04, FR-06, FR-20) | Last executable piece; depends on everything above being durable and buildable. | | 7 | **Repository Documentation** | Website workspace contract (FR-09); README updates for the new `wwwroot` layout and health endpoint; `.env.example` updates | Depends on Unit 6's settled host layout. Operations-facing documents (deployment instructions, rollback plan, monitoring setup, readiness checklist) are produced in the Operations phase, not here. | --- ## 6. Timeline - **Total stages to execute**: 12 (2 remaining Inception + 7 Construction stage-instances across units + Build and Test + 3 Operations) - **Per-unit Construction stage-instances**: Functional Design ×3, NFR Design ×2, Infrastructure Design ×2, Code Generation ×7 - **Estimated duration**: not estimated in wall-clock time. Progress is gated on user approval at every stage boundary, and three items depend on external systems outside this workflow's control: Sentry project and alert-rule creation, Umami website entries, and UptimeRobot monitors. Those are host/service setup steps documented in Operations, not code. --- ## 7. Success Criteria ### Primary Goal A push to `master` builds, tests and deploys the CMS to the test environment without manual steps, and production can be deployed by one deliberate action — on hosting where no server configuration is possible, and without ever endangering the customer's public website, the database, or master↔slave trust. ### Key Deliverables 1. `.gitea/workflows/continuous_integration.yaml` and `.gitea/workflows/deploy.yaml` 2. `wwwroot/admin/` + `wwwroot/web/` serving, with `wwwroot/web/` outside the swapped release directory (ASM-01) 3. `/health` liveness endpoint, on the availability bypass list, never conflated with domain endpoints 4. Sentry on both sides, Umami on both frontends, UptimeRobot monitors for `/health`, `/` and `/admin` 5. HTTP security-headers middleware with a path-scoped CSP 6. Database-backed Data Protection key ring and automatic Core migrations 7. Website workspace contract, deployment instructions, rollback plan, monitoring setup, production readiness checklist 8. A green pipeline: lint clean, no vulnerable packages, all tests passing ### Quality Gates - `dotnet build -c Release`: 0 errors - `dotnet test`: all backend tests pass (219 at baseline, plus new tests) - `dotnet list package --vulnerable --include-transitive`: no advisories - `pnpm run build`: succeeds (includes `tsc -b`) - `pnpm test`: all frontend tests pass (213 at baseline, plus new tests) - `pnpm run lint` and `pnpm run format:check`: clean - No blocking Security Baseline findings at any stage ### Integration Readiness - Both hosts start successfully — `SlpModularCms.Api` **and** `SlpModularCms.Api.Slave`, the latter having no test project and therefore verified by starting it - `dotnet publish` produces the expected `wwwroot` layout with the admin SPA in place - Middleware ordering verified: exception handler → rate limiter → HTTPS redirect → security headers → static files → CORS → availability gate → auth → endpoints, with `/health` reachable while the instance is switched off - The availability gate still blocks `/api/v1` and `/admin` when disabled, and the public website still serves — the pre-existing behaviour recorded in `architecture.md`, deliberately unchanged ### Operational Readiness - A deploy can be rolled back by redeploying the retained previous release without a rebuild - A production deploy is preceded by a verifiable database backup - After a deploy it is determinable, without host access, that the app is alive, whether it is erroring, and whether all expected modules loaded — the last point mattering because `ModuleOrchestrator` logs rather than throws on module load failure --- ## 8. Carried-Forward Items | ID | Item | Handled at | |---|---|---| | ASM-01 | `wwwroot/web/` must live outside the swapped release directory | Infrastructure Design, Unit 6 — **must be confirmed there** | | OPEN-01 | Correlation/request ID mechanism (SECURITY-03) | NFR Design, Unit 4 | | OPEN-02 | `IsAdminBypass` reads the JWT without validating its signature — pre-existing, needs an owner | **Recommend `tech-debt-backlog`**; decide at Application Design whether to fold in | | OPEN-03 | Exact patched versions for the two vulnerable packages | Code Generation, Unit 1 | | OPEN-04 | When FTPS is actually built | Deferred by design (D-02) | | DEV-01…04 | Four accepted security deviations | Re-confirmed at Production Readiness Validation |