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](/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/`

## 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.