From 637dfd2651a8ad7b0900c0a87c714da7750aaae2 Mon Sep 17 00:00:00 2001
From: Citali <git@fellies.email>
Date: Wed, 11 Feb 2026 19:11:45 +0100
Subject: [PATCH] docs(ops): add staging deployment checklist and evidence
 template

---
 TODO.md                                       |   3 +-
 docs/product-engineering/index.md             |   1 +
 .../staging-deployment-checklist.md           | 100 ++++++++++++++++++
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 docs/product-engineering/staging-deployment-checklist.md

diff --git a/TODO.md b/TODO.md
index 6115a60..e4763da 100644
--- a/TODO.md
+++ b/TODO.md
@@ -108,7 +108,7 @@ This file is the single source of truth for roadmap and delivery progress.
 ### MVP0 Close-Out Checklist
 
 - [~] [P1] Verify and document protected branch rules in Gitea (`main`, `staging`)
-- [ ] [P1] Run first staging deployment against a real host with deploy workflow and document result
+- [~] [P1] Run first staging deployment against a real host with deploy workflow and document result
 - [x] [P1] Replace release workflow placeholders with real release-notes and rollback execution steps
 - [x] [P1] Expose runtime version + short git hash in admin and public app footer
 - [x] [P2] Add CI build stamping for version/hash values consumed by app footers
@@ -220,6 +220,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (`VERSIONING.md`).
 - [2026-02-11] Release workflow now publishes changelog-derived notes to Gitea releases and supports executable production rollback via SSH + compose tag switch.
 - [2026-02-11] Branch protection verification checklist is now documented; final UI-level verification remains environment-specific.
+- [2026-02-11] Added a staging deployment execution checklist and deployment-record template to capture first real-host rollout evidence.
 
 ## How We Use This File
 
diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md
index 5407b4e..533ed9b 100644
--- a/docs/product-engineering/index.md
+++ b/docs/product-engineering/index.md
@@ -12,6 +12,7 @@ This section covers platform and implementation documentation for engineers and
 - [CRUD Examples](/product-engineering/crud-examples)
 - [Domain Glossary](/product-engineering/domain-glossary)
 - [Environment Runbook](/product-engineering/environment-runbook)
+- [Staging Deployment Checklist](/product-engineering/staging-deployment-checklist)
 - [Delivery Pipeline](/product-engineering/delivery-pipeline)
 - [Git Flow Governance](/product-engineering/git-flow-governance)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
diff --git a/docs/product-engineering/staging-deployment-checklist.md b/docs/product-engineering/staging-deployment-checklist.md
new file mode 100644
index 0000000..c617b58
--- /dev/null
+++ b/docs/product-engineering/staging-deployment-checklist.md
@@ -0,0 +1,100 @@
+# Staging Deployment Checklist
+
+## Purpose
+
+Operational checklist for the first real staging deployment using `.gitea/workflows/deploy.yml`.
+
+Use this once end-to-end, save the record, then mark MVP0 staging deployment as complete in `TODO.md`.
+
+## Preconditions
+
+- Docker host for staging is reachable via SSH.
+- Gitea repo secrets are configured:
+  - `CMS_STAGING_HOST`
+  - `CMS_STAGING_USER`
+  - `CMS_DEPLOY_KEY`
+  - `CMS_REMOTE_DEPLOY_PATH`
+  - `CMS_IMAGE_REGISTRY`
+  - `CMS_IMAGE_NAMESPACE`
+  - `CMS_IMAGE_REGISTRY_USER`
+  - `CMS_IMAGE_REGISTRY_PASSWORD`
+- Release image tag exists in registry (e.g. `v0.1.0`).
+- Remote deploy path contains:
+  - `docker-compose.staging.yml`
+  - staging env file(s) needed by compose
+
+## Step-by-Step Execution
+
+1. Verify release images exist:
+   - `cms-web:<tag>`
+   - `cms-admin:<tag>`
+2. In Gitea Actions, run `CMS Deploy` workflow.
+3. Inputs:
+   - `environment=staging`
+   - `image_tag=<tag>`
+   - `rollback_tag=` (empty for normal deploy)
+4. Confirm workflow success.
+5. Validate staging endpoints:
+   - web base route
+   - admin login route
+6. Run smoke checks on staging:
+   - auth login
+   - i18n route/switch baseline
+   - admin dashboard route access
+7. If failure:
+   - rerun `CMS Deploy` with `rollback_tag=<previous-tag>`
+   - capture root cause and remediation notes
+
+## Evidence To Capture
+
+- Workflow run URL
+- Deployed image tag
+- Timestamp (UTC)
+- Validation results (pass/fail)
+- Rollback performed or not
+
+## Deployment Record Template
+
+Copy the block below into a new file under `docs/product-engineering/staging-deployments/`.
+
+```md
+# Staging Deployment Record - <YYYY-MM-DD>
+
+- Date (UTC):
+- Operator:
+- Workflow run URL:
+- Target environment: staging
+- Image tag:
+- Previous tag:
+
+## Preconditions
+
+- [ ] Secrets configured in Gitea
+- [ ] Registry images available
+- [ ] Remote compose path verified
+
+## Execution
+
+1. Triggered `CMS Deploy` with `environment=staging`, `image_tag=<tag>`
+2. Workflow status: <!-- pass/fail -->
+
+## Validation
+
+- [ ] Web route check
+- [ ] Admin login route check
+- [ ] Auth smoke flow
+- [ ] i18n smoke flow
+- [ ] Admin dashboard access
+
+## Rollback
+
+- Performed: <!-- yes/no -->
+- Rollback tag:
+- Rollback workflow run URL:
+
+## Outcome
+
+- Result: <!-- success/failed -->
+- Notes:
+- Follow-up actions:
+```