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.