ci: require manual gated releases from main

docs/PORTAINER.md

@@ -17,8 +17,9 @@ Cloudflare R2, so MinIO is not part of this stack.
 
 The single workflow is `.gitea/workflows/deploy.yml`. Every push and pull request
 runs static validation, the integration suite against a real stack, and a secret
-scan. A push to `main` then builds the production images, publishes both `latest`
-and the full commit SHA, reports their vulnerabilities, and calls Portainer.
+scan. A push to `main` does not publish or deploy. A manual workflow run on
+`main` repeats those checks, builds and scans the images, then publishes both
+`latest` and the full commit SHA and calls Portainer.
 
 What actually gates a deployment:
 
@@ -26,17 +27,19 @@ What actually gates a deployment:
 |---|---|
 | `py_compile` and the unit tests | yes |
 | Integration suite on a live stack (smoke, workflow, security, scanning, retention, runtime) | yes |
-| Browser suites | only when the runner has Chrome; otherwise warns and continues |
+| Browser suites | yes; Chrome runs in the Compose test container |
 | Trivy secret scan (HIGH/CRITICAL) | yes |
-| Source preflight (`deploy/production_preflight.py --source-only`) | only when `ENFORCE_PRODUCTION_PREFLIGHT` is `true` |
+| Source preflight (`deploy/production_preflight.py --source-only`) | yes for manual release; advisory on pushes unless `ENFORCE_PRODUCTION_PREFLIGHT` is `true` |
 | Trivy image vulnerabilities, CRITICAL | yes |
-| Trivy image vulnerabilities, HIGH | no — reported after the build |
+| Trivy image vulnerabilities, HIGH | no — reported before publication |
+| Configured Portainer webhook | yes for manual release |
 
-The source preflight is advisory by default because it refuses a release while
-the payment and messaging adapters are fake, which is the deliberate state the
-stack runs in today. Enforcing it now would block every deployment. Set the
-repository variable `ENFORCE_PRODUCTION_PREFLIGHT` to `true` once real adapters
-land, and it becomes a hard gate.
+The source preflight refuses a release while the payment and messaging adapters
+are fake. It remains advisory on push checks so development can continue, but a
+manual release is blocked until those adapters are replaced. Set the repository
+variable `ENFORCE_PRODUCTION_PREFLIGHT` to `true` when all pushes should also
+fail on those blockers. Before a manual release, run the full configuration
+preflight below against the actual Portainer values; CI checks source only.
 
 CRITICAL image findings block. Both images carry none: the bases are pinned by
 digest, both Dockerfiles upgrade their OS packages, and the web image moved off
@@ -60,10 +63,10 @@ Repository secrets:
 - `REGISTRY_USERNAME` and `REGISTRY_TOKEN` — package write credentials.
 - `PORTAINER_WEBHOOK` — webhook generated by the `dtf-cloud` Portainer stack.
 
-The webhook is called only after the gating checks in the table above pass.
+The webhook is called only after the release gates above pass.
 `ENFORCE_PRODUCTION_PREFLIGHT` and `TRIVY_IMAGE` are optional repository
-variables; without them the preflight is advisory and a pinned default scanner
-image is used.
+variables; the former affects push checks and the latter defaults to a pinned
+scanner image.
 
 ## 2. One-time Portainer resources
 
@@ -124,10 +127,13 @@ The `db-init` service completing and stopping is expected. The other six
 services must be healthy. A failed `db-init` task or an unhealthy service blocks
 acceptance.
 
-## 4. Normal deployment
+## 4. Manual deployment
 
-Push to `main`. Gitea validates, tests, scans, publishes these images, and calls
-the webhook:
+Push the reviewed commit to `main` and wait for its validation workflow to pass.
+After validating the actual Portainer configuration with the full preflight in
+section 3, use Gitea Actions to manually run **Build and deploy** on `main` at
+that commit. The workflow repeats validation, tests and scans, then publishes
+these images and calls the webhook:
 
 ```text
 gitea.blyzer.com.br/blyzer/dtf-api:latest