ci: lock deploy workflows across main and master

docs/04-configuration/DEVIN_GITEA_PROXMOX_CICD.md

@@ -0,0 +1,217 @@
+# Devin → Gitea → Proxmox CI/CD
+
+**Status:** Working baseline for this repo  
+**Last Updated:** 2026-04-20
+
+## Goal
+
+Create a repeatable path where:
+
+1. Devin lands code in Gitea.
+2. Gitea Actions validates the repo on the site-wide `act_runner`.
+3. A successful workflow calls `phoenix-deploy-api`.
+4. `phoenix-deploy-api` resolves the repo/branch to a deploy target and runs the matching Proxmox publish command.
+5. The deploy service checks the target health URL before it reports success.
+
+## Current baseline in this repo
+
+The path now exists for **`d-bis/proxmox`** on **`main`** and **`master`**:
+
+- Canonical workflow sources: [.gitea/workflow-sources/deploy-to-phoenix.yml](/home/intlc/projects/proxmox/.gitea/workflow-sources/deploy-to-phoenix.yml) and [.gitea/workflow-sources/validate-on-pr.yml](/home/intlc/projects/proxmox/.gitea/workflow-sources/validate-on-pr.yml)
+- Workflow: [deploy-to-phoenix.yml](/home/intlc/projects/proxmox/.gitea/workflows/deploy-to-phoenix.yml)
+- Manual app workflow: [deploy-portal-live.yml](/home/intlc/projects/proxmox/.gitea/workflows/deploy-portal-live.yml)
+- Deploy service: [server.js](/home/intlc/projects/proxmox/phoenix-deploy-api/server.js)
+- Target map: [deploy-targets.json](/home/intlc/projects/proxmox/phoenix-deploy-api/deploy-targets.json)
+- Current live publish script: [deploy-phoenix-deploy-api-to-dev-vm.sh](/home/intlc/projects/proxmox/scripts/deployment/deploy-phoenix-deploy-api-to-dev-vm.sh)
+- Manual smoke trigger: [trigger-phoenix-deploy.sh](/home/intlc/projects/proxmox/scripts/dev-vm/trigger-phoenix-deploy.sh)
+- Target validator: [validate-phoenix-deploy-targets.sh](/home/intlc/projects/proxmox/scripts/validation/validate-phoenix-deploy-targets.sh)
+- Bootstrap helper: [bootstrap-phoenix-cicd.sh](/home/intlc/projects/proxmox/scripts/dev-vm/bootstrap-phoenix-cicd.sh)
+
+That default target publishes the `phoenix-deploy-api` bundle to **VMID 5700** on the correct Proxmox node and starts the CT if needed.
+
+A second target is now available:
+
+- `portal-live` → runs [sync-sankofa-portal-7801.sh](/home/intlc/projects/proxmox/scripts/deployment/sync-sankofa-portal-7801.sh) and then checks `http://192.168.11.51:3000/`
+
+## Workflow lockstep
+
+Because both `main` and `master` can trigger deploys, deploy behavior is now defined from canonical source files and checked for branch parity.
+
+- Edit only the source files under [.gitea/workflow-sources](/home/intlc/projects/proxmox/.gitea/workflow-sources:1)
+- Sync the checked-in workflow copies with:
+
+```bash
+bash scripts/verify/sync-gitea-workflows.sh
+```
+
+- Validate source sync plus `main`/`master` parity with:
+
+```bash
+bash scripts/verify/run-all-validation.sh --skip-genesis
+```
+
+The deploy and PR workflows both fetch `origin/main` and `origin/master` before validation, so branch drift now fails CI instead of silently changing deploy behavior.
+
+## Flow
+
+```text
+Devin
+  -> push to Gitea
+  -> Gitea Actions on act_runner (5700)
+  -> bash scripts/verify/run-all-validation.sh --skip-genesis
+  -> validates deploy-targets.json structure
+  -> POST /api/deploy to phoenix-deploy-api
+  -> match repo + branch + target in deploy-targets.json
+  -> run deploy command
+  -> verify target health URL
+  -> update Gitea commit status success/failure
+```
+
+## Required setup
+
+### 1. Runner
+
+Bring up the site-wide Gitea runner on VMID **5700**:
+
+```bash
+bash scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh
+```
+
+Reference: [GITEA_ACT_RUNNER_SETUP.md](GITEA_ACT_RUNNER_SETUP.md)
+
+### 0. One-command bootstrap
+
+If root `.env` already contains the needed values, use:
+
+```bash
+bash scripts/dev-vm/bootstrap-phoenix-cicd.sh --repo d-bis/proxmox
+```
+
+This runs the validation gate, deploys `phoenix-deploy-api`, and smoke-checks the service.
+
+### 2. Deploy API service
+
+Deploy the API to the dev VM:
+
+```bash
+./scripts/deployment/deploy-phoenix-deploy-api-to-dev-vm.sh --dry-run
+./scripts/deployment/deploy-phoenix-deploy-api-to-dev-vm.sh --apply --start-ct
+```
+
+On the target VM, set at least:
+
+```bash
+PORT=4001
+GITEA_URL=https://gitea.d-bis.org
+GITEA_TOKEN=<token with repo status access>
+PHOENIX_DEPLOY_SECRET=<shared secret>
+PHOENIX_REPO_ROOT=/home/intlc/projects/proxmox
+```
+
+Optional:
+
+```bash
+DEPLOY_TARGETS_PATH=/opt/phoenix-deploy-api/deploy-targets.json
+```
+
+For the `portal-live` target, also set:
+
+```bash
+SANKOFA_PORTAL_SRC=/home/intlc/projects/Sankofa/portal
+```
+
+### 3. Gitea repo secrets
+
+Set these in the Gitea repository that should deploy:
+
+- `PHOENIX_DEPLOY_URL`
+- `PHOENIX_DEPLOY_TOKEN`
+
+Example:
+
+- `PHOENIX_DEPLOY_URL=http://192.168.11.59:4001/api/deploy`
+- `PHOENIX_DEPLOY_TOKEN=<same value as PHOENIX_DEPLOY_SECRET>`
+
+For webhook signing, the bootstrap/helper path also expects:
+
+- `PHOENIX_DEPLOY_SECRET`
+- `PHOENIX_WEBHOOK_DEPLOY_ENABLED=1` only if you want webhook events themselves to execute deploys
+
+Do not enable both repo Actions deploys and webhook deploys for the same repo unless you intentionally want duplicate deploy attempts.
+
+## Adding more repos or VM targets
+
+Extend [deploy-targets.json](/home/intlc/projects/proxmox/phoenix-deploy-api/deploy-targets.json) with another entry.
+
+Each target is keyed by:
+
+- `repo`
+- `branch`
+- `target`
+
+Each target defines:
+
+- `cwd`
+- `command`
+- `required_env`
+- optional `healthcheck`
+- optional `timeout_sec`
+
+Example shape:
+
+```json
+{
+  "repo": "d-bis/another-service",
+  "branch": "main",
+  "target": "portal-live",
+  "cwd": "${PHOENIX_REPO_ROOT}",
+  "command": ["bash", "scripts/deployment/sync-sankofa-portal-7801.sh"],
+  "required_env": ["PHOENIX_REPO_ROOT"]
+}
+```
+
+Use separate `target` names when the same repo can publish to different VMIDs or environments.
+
+Target-map validation is already part of:
+
+```bash
+bash scripts/verify/run-all-validation.sh --skip-genesis
+```
+
+and can also be run directly:
+
+```bash
+bash scripts/validation/validate-phoenix-deploy-targets.sh
+```
+
+## Manual testing
+
+Before trusting a new Gitea workflow, trigger the deploy service directly:
+
+```bash
+bash scripts/dev-vm/trigger-phoenix-deploy.sh
+```
+
+Trigger the live portal deployment target directly:
+
+```bash
+bash scripts/dev-vm/trigger-phoenix-deploy.sh d-bis/proxmox main portal-live
+```
+
+Inspect configured targets:
+
+```bash
+curl -s http://192.168.11.59:4001/api/deploy-targets | jq .
+```
+
+## Recommended next expansions
+
+- Add a Phoenix API target for the repo that owns VMID **7800** or **8600**, depending on which deployment line is canonical.
+- Add repo-specific workflows once the Sankofa source repos themselves are mirrored into Gitea Actions.
+- Move secret values from ad hoc `.env` files into the final operator-managed secret source once you settle the production host for `phoenix-deploy-api`.
+
+## Notes
+
+- The Gitea workflow is gated by `scripts/verify/run-all-validation.sh --skip-genesis` before deploy.
+- `phoenix-deploy-api` now returns `404` when no matching target exists and `500` when the deploy command fails.
+- Commit status updates are written back to Gitea from the deploy service itself.