proxmox/docs/04-configuration/DEVIN_GITEA_PROXMOX_CICD.md

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:

• Workflow: deploy-to-phoenix.yml
• Manual app workflow: deploy-portal-live.yml
• Deploy service: server.js
• Target map: deploy-targets.json
• Current live publish script: deploy-phoenix-deploy-api-to-dev-vm.sh
• Manual smoke trigger: trigger-phoenix-deploy.sh
• Target validator: validate-phoenix-deploy-targets.sh
• Bootstrap helper: 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 and then checks http://192.168.11.51:3000/

Flow

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 scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh

Reference: GITEA_ACT_RUNNER_SETUP.md

0. One-command bootstrap

If root .env already contains the needed values, use:

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:

./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:

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:

DEPLOY_TARGETS_PATH=/opt/phoenix-deploy-api/deploy-targets.json

For the portal-live target, also set:

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 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:

{
  "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 scripts/verify/run-all-validation.sh --skip-genesis

and can also be run directly:

bash scripts/validation/validate-phoenix-deploy-targets.sh

Manual testing

Before trusting a new Gitea workflow, trigger the deploy service directly:

bash scripts/dev-vm/trigger-phoenix-deploy.sh

Trigger the live portal deployment target directly:

bash scripts/dev-vm/trigger-phoenix-deploy.sh d-bis/proxmox main portal-live

Inspect configured targets:

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.