directus/.planning/phase-1-slice-1-schema/08-gitea-ci-dryrun.md

# Task 1.8 — Gitea CI dry-run workflow

**Phase:** 1 — Slice 1 schema + deploy pipeline
**Status:** ⬜ Not started
**Depends on:** 1.7
**Wiki refs:** `docs/wiki/entities/directus.md` (Schema management section)

## Goal

Build a Gitea Actions workflow that on push to `main` (when relevant paths change): builds the image, spins up a throwaway Postgres + TimescaleDB in CI, runs the entrypoint flow as a **dry-run** to catch snapshot/migration breakage, and only publishes the image to the registry if the dry-run succeeds. Mirrors the `processor` and `tcp-ingestion` workflow shape.

## Deliverables

- `.gitea/workflows/build.yml`:
  ```yaml
  name: Build directus image

  on:
    push:
      branches: [main]
      paths:
        - 'snapshots/**'
        - 'db-init/**'
        - 'extensions/**'
        - 'scripts/**'
        - 'entrypoint.sh'
        - 'Dockerfile'
        - '.gitea/workflows/build.yml'
    workflow_dispatch:

  jobs:
    build-and-publish:
      runs-on: ubuntu-22.04
      services:
        postgres:
          image: timescale/timescaledb-ha:pg16.6-ts2.17.2-all  # match compose.dev.yaml; :pg16-latest does NOT exist on Docker Hub
          env:
            POSTGRES_USER: directus
            POSTGRES_PASSWORD: directus
            POSTGRES_DB: directus
          ports: ['5432:5432']
          options: >-
            --health-cmd "pg_isready -U directus"
            --health-interval 5s
            --health-timeout 5s
            --health-retries 10

      steps:
        - uses: actions/checkout@v4

        - name: Build image
          run: docker build -t trm-directus:ci .

        - name: Dry-run boot against throwaway Postgres
          env:
            DB_HOST: postgres
            DB_PORT: 5432
            DB_USER: directus
            DB_PASSWORD: directus
            DB_DATABASE: directus
            KEY: ci-key-not-secret
            SECRET: ci-secret-not-secret
            ADMIN_EMAIL: ci@example.com
            ADMIN_PASSWORD: ci-password-not-secret
            PUBLIC_URL: http://localhost:8055
          run: |
            docker run --rm \
              -e DB_CLIENT=pg \
              -e DB_HOST=$DB_HOST -e DB_PORT=$DB_PORT \
              -e DB_USER=$DB_USER -e DB_PASSWORD=$DB_PASSWORD -e DB_DATABASE=$DB_DATABASE \
              -e KEY=$KEY -e SECRET=$SECRET \
              -e ADMIN_EMAIL=$ADMIN_EMAIL -e ADMIN_PASSWORD=$ADMIN_PASSWORD \
              -e PUBLIC_URL=$PUBLIC_URL \
              --network host \
              --entrypoint bash \
              trm-directus:ci \
              -c '/directus/scripts/apply-db-init.sh && /directus/scripts/schema-apply.sh && echo "dry-run ok"'

        - name: Login to Gitea registry
          uses: docker/login-action@v3
          with:
            registry: git.dev.microservices.al
            username: ${{ secrets.REGISTRY_USERNAME }}
            password: ${{ secrets.REGISTRY_PASSWORD }}

        - name: Tag and push
          run: |
            docker tag trm-directus:ci git.dev.microservices.al/trm/directus:main
            docker tag trm-directus:ci git.dev.microservices.al/trm/directus:${{ github.sha }}
            docker push git.dev.microservices.al/trm/directus:main
            docker push git.dev.microservices.al/trm/directus:${{ github.sha }}

        - name: Trigger Portainer redeploy (optional)
          if: secrets.PORTAINER_WEBHOOK_URL != ''
          run: curl -X POST "${{ secrets.PORTAINER_WEBHOOK_URL }}"
  ```

## Specification

- **Dry-run runs the entrypoint scripts only**, not `directus start`. Starting the server and waiting for it to serve is slow and unnecessary — the goal is to catch DDL / snapshot apply errors. Override the `ENTRYPOINT` and run the two scripts directly.
- **Service container is the throwaway Postgres.** `services:` block in Gitea Actions (compatible syntax with GitHub Actions). Use the pinned TimescaleDB image; mismatch with prod hides bugs.
- **Path filter on `on.push.paths`** keeps CI quiet for unrelated repo changes (docs-only commits, etc.). Mirrors the processor workflow.
- **Two image tags published:** `:main` (always points at latest main) and `:<sha>` (specific commit, immutable). The deploy stack can pin to either.
- **Portainer webhook is optional** (gated by secret presence). If unset, no auto-deploy.
- **No integration tests in CI for Phase 1.** The dry-run boot *is* the integration test — it proves the snapshot+db-init combination works against a fresh Postgres. Phase 5+ adds extension-specific tests as those land.
- **Required Gitea secrets:**
  - `REGISTRY_USERNAME`, `REGISTRY_PASSWORD` — for the image push.
  - `PORTAINER_WEBHOOK_URL` — optional, for auto-deploy.

## Acceptance criteria

- [ ] Workflow file is committed at `.gitea/workflows/build.yml`.
- [ ] First push to `main` after this lands triggers the workflow.
- [ ] Workflow steps in order: checkout → build → dry-run boot → registry login → tag/push → optional Portainer ping.
- [ ] Dry-run step exits 0 with logs showing "db-init complete" and "schema apply: no changes" (after the snapshot has been applied once, subsequent runs against fresh Postgres still apply from scratch — verify the apply step works in both cases).
- [ ] Intentionally break the snapshot (manually edit `snapshots/schema.yaml` to a malformed YAML) → workflow fails at the dry-run step → image is NOT pushed.
- [ ] Intentionally break a migration (introduce SQL syntax error in `db-init/`) → workflow fails at the dry-run step → image is NOT pushed.
- [ ] Push a docs-only change → workflow does NOT trigger.
- [ ] Image pushed to registry under `git.dev.microservices.al/trm/directus:main` and `:<sha>`.
- [ ] Portainer webhook fires if configured.

## Risks / open questions

- **Gitea Actions `services:` syntax compatibility.** Gitea's runner is mostly GitHub-Actions-compatible but has historically had quirks with the `services:` block (especially around image pulls from private registries). If the throwaway Postgres can't be brought up via `services:`, fall back to a `docker run` step that backgrounds the container and a wait-loop on `pg_isready`. Document the chosen approach.
- **Network access between job container and service container.** `--network host` is the simplest solution if Gitea's runner allows it. If not, use the Docker network created by the runner and reference the service by name (`postgres:5432`).

## Done

**Implementation landed (pending live trigger by first relevant commit).** Workflow file at `.gitea/workflows/build.yml`. Statically validated; live trigger requires a push that touches one of the path-filtered locations.

**Corrections folded in vs. the spec's draft YAML:**

1. **`DB_HOST=localhost`, not `DB_HOST=postgres`.** The spec's draft mixed `--network host` with service-name resolution; those are mutually exclusive. With `--network host` the docker-run container shares the runner's loopback, so the service's port mapping (`5432:5432`) is reachable as `localhost:5432`, not by service name `postgres`. (Service-name resolution would only work with the runner's default bridge network.)
2. **`--health-retries 20`** instead of 10. The `timescaledb-ha:*-all` image runs more init work at startup than vanilla postgres and occasionally exceeds the 50s window on cold runner images. 20 retries × 5s = 100s margin.
3. **`--health-cmd "pg_isready -U directus -d directus"`** with explicit `-d`. Spec had user only.
4. **`curl -fsS -X POST`** for the Portainer webhook step. Bare `curl -X POST` returns 0 even on HTTP 4xx/5xx; `-f` makes a misconfigured webhook URL fail the step explicitly.
5. **Plain `docker build`**, NOT `docker/build-push-action@v5`. The dry-run step needs the freshly-built image accessible to a subsequent `docker run`. `build-push-action` with the docker-container Buildx driver exports into a separate buildkitd cache that `docker run` cannot see — the run would fail with "image not found." Plain `docker build` keeps the image in the local Docker daemon.

**Deliberate divergences from `processor/.gitea/workflows/build.yml`:**

| Aspect | Processor | Directus | Why |
|---|---|---|---|
| Build mechanism | `docker/build-push-action@v5` | plain `docker build` | dry-run needs local-daemon access (above) |
| Buildx setup | yes | no | Buildx isolates the image; would defeat the dry-run |
| `services:` block | absent | present | Directus dry-run needs a live Postgres; processor mocks it |
| Node/pnpm setup | yes | no | No TS to compile in Phase 1 (Phase 5 adds this) |
| typecheck/lint/test | three steps | none | No extensions yet |
| Portainer webhook | unconditional | gated on secret presence | Spec requirement |
| `runs-on` | `ubuntu-latest` | `ubuntu-22.04` | Pin to avoid floating-tag runner image breakage |

**Acceptance criteria status:**

Static (verified):
- ✅ Workflow file at `.gitea/workflows/build.yml`.
- ✅ Steps in correct order: checkout → build → dry-run → login → tag/push → optional Portainer.
- ✅ Path filter excludes `.planning/`, `README.md`, `compose.dev.yaml`, `package.json` — docs-only commits won't trigger CI.
- ✅ Workflow file itself is in the path-filter list (so changes to CI trigger CI).
- ✅ Two image tags published (`:main`, `:<sha>`).
- ✅ Required secrets identified: `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`. Optional: `PORTAINER_WEBHOOK_URL`.
- ✅ Dry-run command logic traced: env vars, network mode, entrypoint override, script chain all consistent.

Pending live trigger (will validate on first push that hits the path filter):
- ⏳ Workflow triggers on push.
- ⏳ Dry-run step exits 0 against a fresh Postgres + the committed snapshot (currently 105 KB, 13 collections).
- ⏳ Snapshot drift simulation: hand-edit `snapshots/schema.yaml` to malformed YAML → push → CI fails at dry-run → image NOT pushed.
- ⏳ Migration syntax error simulation: introduce broken `db-init/006_*.sql` → push → CI fails at dry-run → image NOT pushed.
- ⏳ Image actually published to `git.dev.microservices.al/trm/directus:main` after a clean run.
- ⏳ Portainer webhook fires if configured.

**Operator action required before first run:** in the Gitea repo at `git.dev.microservices.al/trm/directus` → Settings → Secrets, configure:
- `REGISTRY_USERNAME` — Gitea user with write access to the container registry
- `REGISTRY_PASSWORD` — password or PAT for that user
- `PORTAINER_WEBHOOK_URL` (optional) — for auto-redeploy on push

Without `REGISTRY_USERNAME` / `REGISTRY_PASSWORD` the Login step fails with a clear auth error. Without `PORTAINER_WEBHOOK_URL` the Portainer step is skipped entirely.

**Port-allocation correction (2026-05-02):** initial workflow used `5432:5432` for the throwaway-Postgres port mapping. On a self-hosted Gitea runner, the host typically has another Postgres on 5432 (dev stack, stage instance), causing the service container to fail at start with "port already allocated." Fixed by remapping to `15432:5432` (the conventional Postgres-second-instance port) and updating the dry-run's `DB_PORT=15432`. The service container itself still listens on 5432 internally — only the host-side mapping changed. `--network host` semantics are preserved: `DB_HOST=localhost` reaches the service on the runner's loopback at `:15432`.