# Gitea CD/CI — operator checklist

Use this after changing **`phoenix-deploy-api/deploy-targets.json`** or adding workflows under **`config/gitea-workflow-templates/`**.

## One-time per application repo (on Gitea)

1. **Actions enabled** for the org/repo (Gitea settings).
2. **Secrets** on **that repo** (not only global):
   - **`PHOENIX_DEPLOY_URL`** — full URL for `POST` (same shape as **`d-bis/proxmox`** workflows use), typically `http://<dev-vm>:4001/api/deploy` or HTTPS equivalent.
   - **`PHOENIX_DEPLOY_TOKEN`** — bearer token accepted by Phoenix deploy API.
   - **`GITEA_TOKEN`** — used by **Pattern B** single-file portal templates under `config/gitea-workflow-templates/repos/*-portal-ci-and-live.yml` when cloning the monorepo with `oauth2:${GITEA_TOKEN}@…` (read-only is enough).
   - **`GOV_PORTALS_TOKEN`** — used by **Pattern A** split workflows in `Gov_Web_Portals/gov-portals-monorepo` submodules (`GOV_PORTALS_TOKEN` + `http.extraHeader=Authorization: token …`); same minimum scope: read `Gov_Web_Portals/gov-portals-monorepo` on Gitea.
3. **Workflow file** in the repo: copy from [`config/gitea-workflow-templates/repos/README.md`](../config/gitea-workflow-templates/repos/README.md) or use the repo’s existing `.gitea/workflows/*.yml`. **Pattern A vs B:** [`config/gitea-workflow-templates/PORTAL_WORKFLOW_PARITY.md`](../config/gitea-workflow-templates/PORTAL_WORKFLOW_PARITY.md).

### Secrets hygiene (Gitea-only, least privilege)

| Secret | Typical scope | Never |
|--------|----------------|-------|
| **`GITEA_TOKEN`** / **`GOV_PORTALS_TOKEN`** | Read `Gov_Web_Portals/gov-portals-monorepo` (and overlay subtree) for CI | Commit into repo YAML, `.git/config` remote URLs, or logs |
| **`PHOENIX_DEPLOY_TOKEN`** | `POST` Phoenix deploy API only | Reuse as full Gitea admin token |
| **`NPM_PASSWORD`** (operator) | NPMplus API on LAN | Same token as Gitea |

Rotate any token that was ever pasted into a `git remote` URL. Prefer `source scripts/lib/load-project-env.sh` and `git -c "http.extraHeader=Authorization: token …"` for one-off pushes (see [GITEA_GOV_PORTALS_LIVE_SOURCE_OF_TRUTH.md](../04-configuration/GITEA_GOV_PORTALS_LIVE_SOURCE_OF_TRUTH.md)).

## Phoenix deploy host (LAN)

1. **`git pull`** **proxmox** so **`deploy-targets.json`** and **`scripts/deployment/phoenix-deploy-*.sh`** match Gitea **`d-bis/proxmox`** `master` / `main`.
2. Restart or reinstall **phoenix-deploy-api** if you manage it via systemd (see **`phoenix-deploy-api/scripts/install-systemd.sh`**).
3. **`GITEA_TOKEN`** on that host must allow archive fetch for repos you deploy.
4. Optional: set **`PHOENIX_DEPLOY_VERIFY_SHA_ON_BRANCH=1`** on the Phoenix deploy API host so `POST /api/deploy` requests that include **`sha`** must resolve to a commit on the declared **`branch`** (see **`phoenix-deploy-api/README.md`**).

## Verify locally (proxmox clone)

```bash
bash scripts/validation/validate-phoenix-deploy-targets.sh phoenix-deploy-api/deploy-targets.json
bash scripts/verify/report-gitea-cd-parity.sh
```

## Canonical references

- [GITEA_REPO_VM_CD_CI_MATRIX.md](../04-configuration/GITEA_REPO_VM_CD_CI_MATRIX.md)
- [GITEA_GOV_PORTALS_LIVE_SOURCE_OF_TRUTH.md](../04-configuration/GITEA_GOV_PORTALS_LIVE_SOURCE_OF_TRUTH.md)
- [config/gitea-workflow-templates/README.md](../../config/gitea-workflow-templates/README.md)