familysync/.planning/phases/08-gitea-ci/08-RESEARCH.md

Phase 8: Gitea CI — Research

Researched: 2026-06-11 Domain: Gitea Actions / act_runner, GitHub Actions service containers, Playwright CI, Docker registry Confidence: MEDIUM — the runner does not yet exist on the Unraid host (0 runners registered); all runner-mode and service-container behaviour is inferred from Gitea/act docs and community reports and must be confirmed via the runner-probe task.

---

<user_constraints>

User Constraints (from CONTEXT.md)

Locked Decisions

D-01 — Dev-stack bring-up: bare background processes + MariaDB service container. No docker compose, no production image. MariaDB = Gitea service container (shared with integration job). API = background pnpm dev:api (needs build first; dev script is node --watch dist/index.js). PWA Vite dev server = started by Playwright's own webServer config. reuseExistingServer: !process.env.CI means Playwright WILL start Vite itself when CI=true.

D-02 — Harness step must wait for both :3000 (API) and :5173 (Vite) to be ready before Playwright launches. The harness global-setup.ts already polls baseURL/health (proxied to the API) and gates /api/me for DEV_AUTH_BYPASS. CI must additionally ensure the API process is up before global-setup runs. MariaDB readiness uses healthcheck.sh --connect --innodb_initialized (never mysqladmin ping — removed in MariaDB 11).

D-03 — One workflow file with parallel, event-gated jobs. pull_request → main: fast-checks (lint + typecheck + unit tests) in parallel with API-integration job and harness job. push → main (merge): build-and-publish job.

D-04 — Two tags on merge: :latest + :<milestone>-<shortsha> (e.g. v1.1-4303a1b). Milestone string read from PROJECT.md/ROADMAP.md (currently v1.1), not hardcoded inline. Short SHA = first 7 chars of GITHUB_SHA.

D-05 — Full Phase 7 device matrix in CI: iPhone 14/WebKit AND Pixel 7/Chromium. Install WebKit system deps on runner.

D-06 — On harness failure, upload test-results/ (traces/screenshots/videos) as CI artifacts. Reporter 'github' in playwright.config.ts may not render annotations in Gitea — verify and fall back to list+html if so.

Claude's Discretion

• Exact job names, step ordering within a job, pnpm store cache key strategy, whether fast-checks is one job or split.
• Whether API background process is pnpm dev:api vs a built node dist/index.js — pick whatever gives reliable :3000 readiness under DEV_AUTH_BYPASS.
• Registry hostname / image repository path under the Gitea registry.

Deferred Ideas (OUT OF SCOPE)

• ROADMAP.md bookkeeping error (Phase 8 marked completed at line 29 while line 204 says "Not started") — docs cleanup, not CI scope. </user_constraints>

<phase_requirements>

Phase Requirements

ID	Description	Research Support
CI-01	Every PR targeting main runs full regression — lint, typecheck (both apps), unit tests, API integration tests against a MariaDB service container, and the Phase 7 mobile Playwright harness (CI brings up API + PWA dev servers + MariaDB + DEV_AUTH_BYPASS) — result gates merge.	See §Architecture Patterns for job topology, §Service Containers for MariaDB, §Dev-Stack Bring-Up for harness orchestration, §Runner-Probe Checklist for what must be verified first.
CI-02	On merge to main, API Docker image is built and published to the Gitea container registry.	See §Docker Registry Push for Gitea registry mechanics, §Image Tagging for v1.1-<sha> strategy.

</phase_requirements>

---

Summary

Phase 8 adds a single .gitea/workflows/ci.yml file that delivers a PR regression gate and a merge-triggered publish job. The technical unknowns cluster around three areas that all require a runner-probe task before anything else is trusted: (1) which GitHub Actions marketplace actions resolve on this self-hosted act_runner and in what runner mode it operates; (2) whether the services: key starts MariaDB when the runner runs jobs in Docker-container mode (the recommended mode), and what hostname the job container uses to reach it; (3) whether actions/upload-artifact@v4 works on Gitea 1.26 or whether the gitea-upload-artifact fork is required.

The single most important finding: service containers (services:) work when act_runner runs jobs in Docker-container mode (the default), but are NOT supported when the runner is configured for host-executor mode. The runner-probe's first task is to determine which mode the Unraid runner is in. If the runner is in host mode, the plan must pivot: either spin up MariaDB via a docker run step in the workflow (instead of services:), or request that the runner be reconfigured to Docker mode.

For the publish job, the Gitea container registry path is git.bergerhouse.net/luckberg/<image>. The built-in GITHUB_TOKEN does NOT work for Gitea package registry pushes — a PAT with write:package scope stored as a repository secret is required. docker/login-action@v3 + docker/build-push-action@v6 resolve from GitHub by default (via DEFAULT_ACTIONS_URL) and appear to work in most Gitea installations; the runner-probe confirms.

Primary recommendation: Write the workflow in three phases — (W0) a runner-probe-only workflow that prints Node/pnpm/Docker versions and tests the key assumptions; (W1) the fast-checks + integration jobs; (W2) the harness job + publish job. Each wave is committed only after the previous wave's probe confirms the assumptions it depends on.

---

Architectural Responsibility Map

Capability	Primary Tier	Secondary Tier	Rationale
Workflow orchestration	CI runner (Gitea Actions)	—	Gitea Actions owns job scheduling
MariaDB service container	CI runner (act_runner Docker daemon)	—	Spawned as a sibling container by act_runner
API background process	CI runner (host or job container)	—	pnpm build && node dist/index.js in a step
Vite dev server	Playwright webServer config	—	Playwright starts it; reuseExistingServer=false in CI
DB seed (global-setup)	Playwright globalSetup	API (through mysql2 direct connection)	global-setup.ts connects directly to MariaDB
Docker image build	CI runner (Docker socket / DinD)	—	docker build in a workflow step
Container registry push	Gitea package registry	—	docker push git.bergerhouse.net/luckberg/familysync-api
Artifact upload (traces)	Gitea Actions artifact storage	—	Via gitea-upload-artifact fork (see §Artifacts)

---

Standard Stack

Workflow Actions

Action	Version	Purpose	Status
actions/checkout	@v4	Clone repo into job	[ASSUMED] Mirrored at gitea.com/actions/checkout; resolves from GitHub by default via DEFAULT_ACTIONS_URL. Probe confirms.
actions/setup-node	@v4	Pin Node.js 22	[ASSUMED] Mirrored at gitea.com/actions/setup-node. Probe confirms.
actions/cache	@v4	pnpm store cache	[ASSUMED] Known networking issue: cache server runs in runner container but job container is on a different network. May time out. Probe is required — fall back to no-cache if it fails.
https://github.com/ChristopherHX/gitea-upload-artifact	@v4	Upload Playwright traces	[VERIFIED: github.com/ChristopherHX/gitea-upload-artifact] Required replacement for actions/upload-artifact@v4 which detects Gitea as GHES and aborts.
docker/login-action	@v3	Authenticate to Gitea registry	[ASSUMED] Referenced from GitHub by absolute URL; probe confirms.
docker/build-push-action	@v6	Build and push Docker image	[ASSUMED] Referenced from GitHub by absolute URL; probe confirms.

No pnpm/action-setup needed

The repo root package.json declares "packageManager": "pnpm@11.5.1". With Node.js installed via actions/setup-node, enabling corepack via corepack enable pnpm in a step is sufficient. [ASSUMED] — probe confirms pnpm is resolvable this way.

Workflow file location

.gitea/workflows/ci.yml — Gitea primarily reads .gitea/workflows/. Both .gitea/ and .github/ are supported, but having files in .gitea/ takes precedence. [CITED: docs.gitea.com/usage/actions/quickstart]

---

Package Legitimacy Audit

Only gitea-upload-artifact is an external action introduced by this phase. All other tools are GitHub-maintained official actions or Docker-maintained actions that are well-established.

Package / Action	Registry / Source	Age	Downloads	Source Repo	Verdict	Disposition
actions/checkout@v4	github.com/actions/checkout	5+ yrs	Millions	github.com/actions/checkout	OK	Approved
actions/setup-node@v4	github.com/actions/setup-node	5+ yrs	Millions	github.com/actions/setup-node	OK	Approved
actions/cache@v4	github.com/actions/cache	5+ yrs	Millions	github.com/actions/cache	OK	Approved — but probe may fall back
ChristopherHX/gitea-upload-artifact@v4	github.com/ChristopherHX/gitea-upload-artifact	~2 yrs	Moderate, known fix for Gitea	github.com/ChristopherHX/gitea-upload-artifact	OK	Approved — known and cited solution to v4 GHES blocker
docker/login-action@v3	github.com/docker/login-action	4+ yrs	Millions	github.com/docker/login-action	OK	Approved
docker/build-push-action@v6	github.com/docker/build-push-action	4+ yrs	Millions	github.com/docker/build-push-action	OK	Approved

Packages removed due to SLOP verdict: none Packages flagged as suspicious SUS: none

---

Runner-Probe Checklist

This is the single most important planning output for Phase 8. Every runner assumption MUST be confirmed by running a minimal probe workflow before the real CI steps are designed.

The runner-probe workflow lives at .gitea/workflows/runner-probe.yml, runs only on a named test branch (e.g. gsd/phase-08-gitea-ci), and does nothing destructive.

What the probe must answer

#	Check	Command in Probe	What it confirms
P-01	Node.js version	node --version	Node 22 available or needs setup-node
P-02	pnpm availability	pnpm --version OR corepack enable pnpm && pnpm --version	pnpm reachable; version matches 11.x
P-03	Runner mode	`cat /proc/1/cgroup	head -5andhostnameandls /.dockerenv 2>/dev/null`	Is the job running in a Docker container (act_runner Docker mode) or on bare host? This is the critical fork: service containers only work in Docker mode.
P-04	Docker socket access	`docker info 2>&1	head -10`	Docker accessible from job; needed for service containers AND publish job
P-05	Service container spawn	Add services: mariadb: image: mariadb:11 to probe job; check if docker ps in a step shows the mariadb container	Service containers work at all
P-06	MariaDB reachability	After P-05: mysql -h 127.0.0.1 -P 3306 -u root -proot -e "SELECT 1" (host runner) OR -h mariadb (job container)	Which hostname resolves to the MariaDB service
P-07	actions/checkout	uses: actions/checkout@v4	Action resolves; DEFAULT_ACTIONS_URL is set to github.com
P-08	actions/setup-node	uses: actions/setup-node@v4 with node-version: '22'	setup-node works; pins Node 22
P-09	actions/cache	uses: actions/cache@v4 with a test key	Cache works without timeout; if it hangs, confirm no-cache fallback
P-10	Playwright deps (WebKit)	`npx playwright install --with-deps webkit chromium 2>&1	tail -20`	System deps installed; no sudo/apt failures
P-11	upload-artifact	uses: https://github.com/ChristopherHX/gitea-upload-artifact@v4 with a dummy file	Upload succeeds; artifact appears in Gitea UI
P-12	Docker login + push	`echo $SECRET	docker login git.bergerhouse.net --username luckberg --password-stdin`	Registry auth works with PAT
P-13	GITHUB_SHA	echo ${GITHUB_SHA:0:7}	Short SHA expression produces 7-char string

Critical fork: Docker mode vs host mode (P-03)

If job runs in a Docker container (Docker mode — the recommended act_runner default):

• Service container hostname = service label name (e.g. mariadb)
• Job container and service container share a Docker network automatically
• DB_HOST=mariadb in job env; NO port mapping needed in workflow
• This is the GitHub-Actions-compatible path; service containers work as documented

If job runs directly on host (host mode):

• Service containers are NOT supported by act_runner's host executor [CITED: github.com/nektos/act/issues/2711]
• The plan must use a docker run -d --name mariadb mariadb:11 ... step instead of services:
• DB_HOST=127.0.0.1 with port 3306:3306 mapping in the docker run step
• Explicit readiness loop step required (no options: health-check auto-wait)
• This is the fallback path; probe determines if it applies

---

CONFIRMED-vs-VERIFY Table

Item	Status	Notes
Workflow file at .gitea/workflows/ci.yml	CONFIRMED	[CITED: docs.gitea.com/usage/actions/quickstart]
on: pull_request and on: push triggers	CONFIRMED	Standard GitHub Actions syntax; Gitea supports these [CITED: comparison page]
actions/checkout@v4 resolves from GitHub	CONFIRMED (per docs)	DEFAULT_ACTIONS_URL defaults to github.com; VERIFY-ON-RUNNER (P-07)
actions/setup-node@v4 resolves	ASSUMED	Mirrored at gitea.com/actions/setup-node; VERIFY-ON-RUNNER (P-08)
actions/cache@v4 works in Docker mode	ASSUMED with caveat	Known networking issue between runner container and job container; VERIFY-ON-RUNNER (P-09)
services: key starts MariaDB in Docker mode	ASSUMED from GitHub Actions docs	act_runner implements this for Docker mode; does NOT implement for host mode [CITED: nektos/act#2711]; VERIFY-ON-RUNNER (P-03 + P-05)
MariaDB hostname in Docker mode = service name	ASSUMED from GitHub Actions semantics	"hostname automatically mapped to label name" for containerized jobs [CITED: docs.github.com]; VERIFY-ON-RUNNER (P-06)
MariaDB hostname in host mode = 127.0.0.1	CONFIRMED for host-mode + port-mapped service	[CITED: firefart.at MySQL-GitHub-Actions]
healthcheck.sh --connect --innodb_initialized works in options:	CONFIRMED	[CITED: mariadb.com/docs healthcheck.sh page]
mysqladmin ping does NOT work with MariaDB 11	CONFIRMED	mysqladmin binary was removed from the mariadb:11 image [CITED: github.com/mage-os/github-actions/issues/365]
actions/upload-artifact@v4 works natively on Gitea	CONFIRMED BROKEN	Gitea detected as GHES; v4 aborts with reqPackageAccess error [CITED: github.com/go-gitea/gitea/issues/31256]
ChristopherHX/gitea-upload-artifact@v4 works	ASSUMED	Known workaround; VERIFY-ON-RUNNER (P-11)
reporter: 'github' renders annotations in Gitea	UNCONFIRMED	Gitea does not fully implement GitHub workflow commands; annotations likely silently ignored. VERIFY-ON-RUNNER — fall back to ['list', 'html'] if annotations don't appear
GITHUB_SHA available in Gitea Actions	CONFIRMED	Gitea uses GitHub-compatible env var names [CITED: forum.gitea.com/t/using-github-sha-or-gitea-sha]
Short SHA via ${GITHUB_SHA:0:7}	CONFIRMED	Bash substring; same forum thread
Docker login to Gitea registry with PAT	CONFIRMED (approach)	secrets.GITEA_TOKEN does NOT work for packages [CITED: forum.gitea.com/t/proper-container-registry-procedure]; use PAT with write:package scope [CITED: docs.gitea.com/usage/packages/container]
Gitea registry image path: git.bergerhouse.net/luckberg/<image>	CONFIRMED	Registry uses {host}/{owner}/{image} format [CITED: docs.gitea.com/usage/packages/container]
docker/login-action@v3 + docker/build-push-action@v6 resolve	ASSUMED	Referenced by absolute GitHub URL; VERIFY-ON-RUNNER (P-12)
Playwright --with-deps installs system deps without sudo	CONFIRMED for most cases	Playwright handles su internally; may fail if runner has no internet/apt access [CITED: playwright.dev/docs/ci]
npx playwright install does NOT cache browser binaries	CONFIRMED (deliberate)	Playwright explicitly recommends against caching browser binaries in CI [CITED: playwright.dev/docs/ci]

---

Architecture Patterns

System Architecture Diagram

PR opened / push to main
        │
        ▼
.gitea/workflows/ci.yml
        │
        ├─── on: pull_request ──────────────────────────────────────────────┐
        │         │                                                          │
        │    ┌────▼──────────────────┐   ┌──────────────────┐              │
        │    │   fast-checks job     │   │  api-integration  │             │
        │    │ (parallel)            │   │  job (parallel)   │             │
        │    │ • pnpm install        │   │ • MariaDB service │             │
        │    │ • lint                │   │ • pnpm install    │             │
        │    │ • typecheck api+pwa   │   │ • drizzle migrate │             │
        │    │ • vitest unit tests   │   │ • vitest run      │             │
        │    └───────────────────────┘   │   (api only)      │             │
        │                                └──────────────────┘              │
        │    ┌──────────────────────────────────────────────────────────┐  │
        │    │   harness job (parallel)                                 │  │
        │    │ • MariaDB service container (shared need, same pattern)  │  │
        │    │ • pnpm install                                           │  │
        │    │ • drizzle generate + migrate                             │  │
        │    │ • pnpm build (api) → node dist/index.js &              │  │
        │    │ • wait :3000 /health                                     │  │
        │    │ • DEV_AUTH_BYPASS=true CI=true PLAYWRIGHT_BASE_URL=...   │  │
        │    │ • pnpm test:e2e (Playwright starts Vite :5173 itself)    │  │
        │    │ • upload test-results/ on failure                        │  │
        │    └──────────────────────────────────────────────────────────┘  │
        │                                                                   │
        └─── on: push (main) ───────────────────────────────────────────────┘
                  │
        ┌─────────▼──────────────┐
        │   publish job          │
        │ • docker login (PAT)   │
        │ • docker build         │
        │   --target production  │
        │ • docker push :latest  │
        │ • docker push :v1.1-sha│
        └────────────────────────┘

Recommended Project Structure

.gitea/
└── workflows/
    ├── runner-probe.yml    # Wave 0: probe only, runs on feature branch
    └── ci.yml              # Waves 1-2: real CI after probe passes

Pattern 1: MariaDB Service Container (Docker-mode runner)

What: Declare MariaDB as a services: entry; act_runner starts it as a sibling container on the same Docker network as the job container. Job reaches it by service label hostname.

When to use: Runner probe P-03 confirms the job runs in a Docker container (Docker mode).

# Source: [ASSUMED from GitHub Actions docs + MariaDB docs]
jobs:
  api-integration:
    runs-on: self-hosted
    services:
      mariadb:
        image: mariadb:11
        env:
          MARIADB_ROOT_PASSWORD: root
          MARIADB_DATABASE: familysync
          MARIADB_USER: familysync
          MARIADB_PASSWORD: testpass
        options: >-
          --health-cmd="healthcheck.sh --connect --innodb_initialized"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=10
          --health-start-period=30s
    env:
      DB_HOST: mariadb # service label name — Docker mode only
      DB_PORT: 3306
      DB_USER: familysync
      DB_PASSWORD: testpass
      DB_NAME: familysync

Critical note on --health-start-period: MariaDB 11 takes longer to initialize InnoDB than older versions. Set --health-start-period=30s to avoid premature health-check failures during container startup. [ASSUMED based on MariaDB 11 init time; tune in probe]

Pattern 2: MariaDB Without Service Containers (host-mode runner fallback)

What: If P-03 shows host mode, start MariaDB manually with docker run -d in a step and do an explicit readiness loop.

When to use: Runner probe P-03 shows job runs directly on host (host mode).

# Source: [ASSUMED — standard workaround for host-mode runners]
steps:
  - name: Start MariaDB
    run: |
      docker run -d --name mariadb \
        -e MARIADB_ROOT_PASSWORD=root \
        -e MARIADB_DATABASE=familysync \
        -e MARIADB_USER=familysync \
        -e MARIADB_PASSWORD=testpass \
        -p 3306:3306 \
        mariadb:11
  - name: Wait for MariaDB
    run: |
      deadline=$((SECONDS + 90))
      until healthcheck_output=$(docker exec mariadb healthcheck.sh --connect --innodb_initialized 2>&1) \
            && [ $? -eq 0 ]; do
        if [ $SECONDS -ge $deadline ]; then
          echo "MariaDB did not become ready in time"
          docker logs mariadb | tail -30
          exit 1
        fi
        sleep 3
      done
      echo "MariaDB ready"
env:
  DB_HOST: 127.0.0.1 # host-mode: service on Docker host reachable via localhost
  DB_PORT: 3306

Pattern 3: API Background Process

What: Build the API, start it as a background process, wait for :3000/health.

When to use: Harness job only (CI-01 harness step).

# Source: [ASSUMED — standard CI background-process pattern]
- name: Build API
  run: pnpm --filter @familysync/api build
  env:
    NODE_ENV: development

- name: Start API
  run: |
    NODE_ENV=development \
    DEV_AUTH_BYPASS=true \
    DB_HOST=${{ env.DB_HOST }} \
    DB_USER=familysync \
    DB_PASSWORD=testpass \
    DB_NAME=familysync \
    node apps/api/dist/index.js &
    echo $! > /tmp/api.pid
    echo "API PID: $(cat /tmp/api.pid)"

- name: Wait for API (:3000)
  run: |
    deadline=$((SECONDS + 60))
    until curl -sf http://localhost:3000/health > /dev/null 2>&1; do
      if [ $SECONDS -ge $deadline ]; then
        echo "API did not start in time"
        kill $(cat /tmp/api.pid) 2>/dev/null || true
        exit 1
      fi
      sleep 2
    done
    echo "API ready"

Why node apps/api/dist/index.js not pnpm dev:api: The dev script is node --watch dist/index.js — it needs a prior pnpm --filter @familysync/api build (tsc). Running via node directly (without --watch) is cleaner for CI since the file watcher is irrelevant. D-discretion covers this choice.

Pattern 4: Drizzle Migration in CI

What: Run drizzle-kit generate (idempotent, generates SQL from schema if needed) then drizzle-kit migrate against the service container. Do NOT use db:push (documented as unsafe on MariaDB — project memory drizzle-mariadb-push-unsafe).

# Source: [ASSUMED — confirmed in project memory and PITFALLS section]
- name: Run DB migrations
  run: pnpm --filter @familysync/api db:migrate
  env:
    DB_HOST: ${{ env.DB_HOST }}
    DB_PORT: 3306
    DB_USER: familysync
    DB_PASSWORD: testpass
    DB_NAME: familysync

Migrations live at apps/api/src/db/migrations/. The db:migrate script calls drizzle-kit migrate which applies existing SQL files — safe because the schema SQL is already in the repo (from generate runs during development). No generate step needed in CI unless the schema changed in the same PR.

Pattern 5: Playwright Harness in CI

What: Run the full Phase 7 harness against the CI-brought-up dev stack. Playwright's webServer starts Vite (:5173) automatically when CI=true (because reuseExistingServer: !process.env.CI is false). The global-setup.ts handles the DB seed and the /health + /api/me readiness gates.

# Source: [ASSUMED — based on playwright.config.ts and global-setup.ts already in repo]
- name: Install Playwright browsers
  run: npx playwright install --with-deps webkit chromium
  working-directory: apps/pwa

- name: Run Playwright harness
  run: pnpm test:e2e
  env:
    CI: true
    PLAYWRIGHT_BASE_URL: http://localhost:5173
    DEV_AUTH_BYPASS: 'true'
    NODE_ENV: development
    DB_HOST: ${{ env.DB_HOST }}
    DB_PORT: 3306
    DB_USER: familysync
    DB_PASSWORD: testpass
    DB_NAME: familysync

- name: Upload test artifacts
  if: failure()
  uses: https://github.com/ChristopherHX/gitea-upload-artifact@v4
  with:
    name: playwright-traces-${{ github.run_id }}
    path: apps/pwa/test-results/
    retention-days: 14

Note on working-directory for playwright install: npx playwright install must be run from the package root where @playwright/test is installed — apps/pwa/. [ASSUMED]

Pattern 6: Docker Image Publish

# Source: [ASSUMED — based on Gitea container registry docs and forum]
publish:
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  runs-on: self-hosted
  steps:
    - uses: actions/checkout@v4

    - name: Compute image tags
      id: tags
      run: |
        SHORT_SHA=${GITHUB_SHA:0:7}
        MILESTONE="v1.1"  # read from PROJECT.md in executor if preferred
        echo "latest=git.bergerhouse.net/luckberg/familysync-api:latest" >> $GITHUB_OUTPUT
        echo "sha_tag=git.bergerhouse.net/luckberg/familysync-api:${MILESTONE}-${SHORT_SHA}" >> $GITHUB_OUTPUT

    - name: Docker login
      run: |
        echo "${{ secrets.GITEA_REGISTRY_PAT }}" | \
        docker login git.bergerhouse.net \
          --username luckberg \
          --password-stdin

    - name: Build and push
      run: |
        docker build \
          --target production \
          -t ${{ steps.tags.outputs.latest }} \
          -t ${{ steps.tags.outputs.sha_tag }} \
          .
        docker push ${{ steps.tags.outputs.latest }}
        docker push ${{ steps.tags.outputs.sha_tag }}

Secret name: GITEA_REGISTRY_PAT — a PAT with write:package (and read:package) scope created by luckberg. Must be added to the repo secrets in Gitea UI before the publish job runs.

Why not docker/login-action: --password-stdin via a direct docker login step is simpler to verify on a self-hosted runner and avoids a dependency on the action resolving. The action is an option but the shell form is safer as a first iteration.

Anti-Patterns to Avoid

• mysqladmin ping in MariaDB 11 health check: The mysqladmin binary is not in the mariadb:11 image. Use healthcheck.sh --connect --innodb_initialized. [CONFIRMED: mage-os/github-actions issue]
• drizzle-kit push in CI: Documented as unsafe on MariaDB — emits false destructive diff that TRUNCATEs tables. Always use generate + migrate. [CONFIRMED: project memory]
• secrets.GITHUB_TOKEN for Gitea registry push: Returns unauthorized: reqPackageAccess. Use a PAT. [CONFIRMED: Gitea forum]
• actions/upload-artifact@v4 natively on Gitea: Fails with GHES detection. Use ChristopherHX/gitea-upload-artifact@v4. [CONFIRMED: Gitea issue #31256]
• reporter: 'github' assumed to render in Gitea: Gitea does not implement the GitHub workflow-command protocol for annotations. The reporter setting in playwright.config.ts currently hardcodes 'github' when CI=true. The planner must add a step that overrides reporter to ['list', 'html'] OR passes --reporter=list to the playwright test invocation. [ASSUMED — verify in probe]
• Starting API with pnpm dev:api without building first: pnpm dev:api is pnpm --filter @familysync/api dev = node --watch dist/index.js, which requires dist/ to exist. In CI, dist/ does not exist until pnpm --filter @familysync/api build (tsc) runs. Build first.
• actions/cache without confirming it works: The cache action has a known networking issue in act_runner Docker mode — the cache server runs in the runner container but the job container is on a different network, causing socket hang-up. Do not assume cache works; probe first and make it optional.
• node-cron in the API background process: Not applicable to CI (short-lived process), but confirming the API uses setInterval (fixed in project) — no concern for CI.

---

Dev-Stack Bring-Up for the Harness Job

The orchestration order is critical. All of the following must be sequential within the harness job (not parallelizable):

1. MariaDB service container starts (via `services:` or `docker run -d` step)
   └── Wait: options health-check (Docker mode) OR explicit loop (host mode)
       Target: `healthcheck.sh --connect --innodb_initialized`
       Timeout: up to 90s (MariaDB 11 init is slower than 10)

2. pnpm install (workspace)

3. drizzle-kit migrate (DB_HOST = mariadb or 127.0.0.1 per runner mode)

4. pnpm --filter @familysync/api build  (produces dist/index.js)

5. Start API background process:
   NODE_ENV=development DEV_AUTH_BYPASS=true node apps/api/dist/index.js &

6. Wait for :3000/health (curl retry loop, 60s timeout)
   This is SEPARATE from global-setup.ts's poll — global-setup runs AFTER
   Playwright starts, and it polls the Vite proxy. The step-level wait ensures
   the API is up before Playwright even attempts to start Vite.

7. Playwright invocation (pnpm test:e2e):
   a. Playwright webServer starts Vite :5173 (reuseExistingServer=false in CI)
   b. global-setup.ts polls baseURL/health (proxied to :3000) — already up from step 6
   c. global-setup.ts gates /api/me for DEV_AUTH_BYPASS confirmation
   d. global-setup.ts seeds DB via mysql2 direct connection (DB_HOST, etc.)
   e. Specs run against both iPhone 14/WebKit and Pixel 7/Chromium

8. On failure: upload test-results/ via gitea-upload-artifact

Note on PLAYWRIGHT_BASE_URL: Set to http://localhost:5173. The Vite dev server proxies /health, /api, /callback → http://localhost:3000. This is how global-setup reaches the API health endpoint through the Vite proxy URL.

Note on NODE_ENV: The global-setup.ts refuses to run if NODE_ENV=production. In CI, set NODE_ENV=development (or leave unset; the guard only blocks production). Do NOT set NODE_ENV=test — the API checks NODE_ENV=development for dev-bypass activation confirmation.

Note on both MariaDB connections: The API (via Drizzle/mysql2) and global-setup.ts (via mysql2 direct) both use the same DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME env vars. Set them once at job level and they propagate to both.

---

Docker Registry Push (CI-02)

Registry Details

Property	Value	Source
Registry host	git.bergerhouse.net	[CONFIRMED from git remote URL]
Image path format	git.bergerhouse.net/{owner}/{image}	[CITED: docs.gitea.com/usage/packages/container]
Image name	git.bergerhouse.net/luckberg/familysync-api	[ASSUMED — owner = luckberg, image name = familysync-api]
Auth method	PAT with write:package scope	[CONFIRMED: Gitea forum, registry docs]
Token variable	secrets.GITEA_REGISTRY_PAT	[ASSUMED — name chosen by planner/executor]
docker login approach	echo $PAT | docker login git.bergerhouse.net --username luckberg --password-stdin	[CONFIRMED: Pitfall 13]

Image Tag Strategy (D-04)

Tag	Example	Purpose
:latest	git.bergerhouse.net/luckberg/familysync-api:latest	Moving pointer for easy pulls
:<milestone>-<shortsha>	git.bergerhouse.net/luckberg/familysync-api:v1.1-4303a1b	Immutable, rollback-traceable

The milestone string v1.1 is hardcoded in the workflow as MILESTONE="v1.1" for now (reading it from PROJECT.md dynamically adds complexity with minimal benefit). The executor can make it a workflow-level env var for easy updates.

Short SHA: ${GITHUB_SHA:0:7} — confirmed available in Gitea Actions. [CITED: forum.gitea.com]

Dockerfile Build Context

The apps/api/Dockerfile must be built from the repo root (not apps/api/), as documented in the Dockerfile header:

docker build --target production -f apps/api/Dockerfile .

This is because the Dockerfile copies the pnpm workspace manifest and lockfile from the repo root. Building from apps/api/ would fail.

---

Common Pitfalls

Pitfall 1: Service Containers Don't Start (Host Mode Runner)

What goes wrong: services: in the workflow YAML is silently ignored; MariaDB container never appears in docker ps. API integration tests fail with ECONNREFUSED to DB.

Why it happens: act_runner in host-executor mode does not implement service container lifecycle [CITED: github.com/nektos/act/issues/2711]. The act_runner runs jobs directly on the host OS and has no mechanism to start sidecar containers.

How to avoid: Probe P-03 detects the runner mode. If host mode: use docker run -d mariadb:11 in a step instead of services:.

Warning signs: P-05 shows MariaDB container not in docker ps.

Pitfall 2: MariaDB 11 Health Check With mysqladmin (Pitfall 11)

What goes wrong: --health-cmd="mysqladmin ping" in options: causes the health check to always fail; the job times out waiting for the service to become healthy.

Why it happens: mysqladmin binary was removed from the official mariadb:11 Docker image.

How to avoid: Use --health-cmd="healthcheck.sh --connect --innodb_initialized" exclusively. [CONFIRMED: mariadb.com docs]

Warning signs: Job hangs at service startup; docker inspect shows container in unhealthy state.

Pitfall 3: Drizzle-Kit Push in CI

What goes wrong: drizzle-kit push emits a destructive diff (TRUNCATEs tables) on populated MariaDB. The CI DB has just been seeded by global-setup.ts; running push afterwards would wipe it.

Why it happens: MariaDB metadata misread by Drizzle's mysql dialect (project memory: drizzle-mariadb-push-unsafe).

How to avoid: Always drizzle-kit migrate in CI (applies existing SQL migration files). Never drizzle-kit push.

Pitfall 4: API Started Without Building First

What goes wrong: node apps/api/dist/index.js fails with MODULE_NOT_FOUND because dist/ does not exist in CI.

Why it happens: dist/ is gitignored; the repo checkout has no compiled output.

How to avoid: Always run pnpm --filter @familysync/api build (= tsc) before starting the API process.

Pitfall 5: Reporter 'github' Emits Invisible Annotations in Gitea (Pitfall from D-06)

What goes wrong: playwright.config.ts sets reporter: 'github' when CI=true. This emits ::error:: GitHub workflow commands, which Gitea Actions does not render as UI annotations. Test failures appear in raw log output only, with no visual callout in the PR.

Why it happens: Gitea Actions does not implement GitHub's workflow command annotation protocol.

How to avoid: The CI env var triggers the 'github' reporter. Override with --reporter=list,html on the playwright test invocation in CI, OR modify the harness job step to set PLAYWRIGHT_REPORTER=list if Playwright honours that env var. The planner should add a PLAYWRIGHT_REPORTER override. Runner probe P-06 (effectively) confirms this.

Warning signs: PR shows no inline annotation for a test failure; only the raw job log shows the failure.

Pitfall 6: actions/upload-artifact@v4 GHES Detection

What goes wrong: Upload step fails with Error: This version of upload-artifact is not supported. Only GHES version X.Y.Z and above is supported.

Why it happens: Gitea is detected as GitHub Enterprise Server; actions/upload-artifact@v4 has a version gate that rejects GHES below a certain version.

How to avoid: Use https://github.com/ChristopherHX/gitea-upload-artifact@v4 instead. [CONFIRMED: Gitea issue #28853 + #31256]

Pitfall 7: actions/cache Socket Hang-Up in Docker Mode

What goes wrong: Cache step hangs and eventually times out with socket hang up. This may only appear intermittently.

Why it happens: act_runner's cache server runs in the runner container; the job container is on a different Docker network and cannot reach the runner's cache server by its configured address. [CITED: docs.gitea.com/usage/actions/act-runner — cache section]

How to avoid: Probe P-09 tests this. If cache consistently fails, skip it — pnpm install without cache on a fast network takes ~30s. Accept it.

Pitfall 8: DEV_AUTH_BYPASS Not Propagated to API Process

What goes wrong: API starts, /health returns 200, but /api/me returns 302 redirect to Authelia. global-setup.ts's DEV_AUTH_BYPASS gate (WR-01) throws a clear error, but the root cause is that DEV_AUTH_BYPASS=true was not exported into the API background process environment.

Why it happens: If the env var is set at the step level but the node process is launched with & in a separate run: step, environment inheritance between steps is not guaranteed in all runner modes.

How to avoid: Pass DEV_AUTH_BYPASS=true inline on the same line as the node invocation (DEV_AUTH_BYPASS=true node apps/api/dist/index.js &) rather than relying on inherited step env.

---

Don't Hand-Roll

Problem	Don't Build	Use Instead	Why
MariaDB health check	Custom TCP-ping script	healthcheck.sh --connect --innodb_initialized	Ships in the mariadb:11 image; handles InnoDB init correctly
Upload artifacts to Gitea	curl to Gitea API	ChristopherHX/gitea-upload-artifact@v4	upload-artifact v4 protocol is complex; the fork wraps it correctly
Docker registry auth	Hand-rolled auth header	docker login --password-stdin	Prevents PAT from appearing in process list
Playwright browser install	Manual apt package list	npx playwright install --with-deps	Playwright knows the correct system deps for each browser version
API readiness check	Arbitrary sleep	curl retry loop against /health	Sleep is flaky; a deterministic health poll is both faster and correct
CI MariaDB in host mode	mysqladmin ping loop	docker exec mariadb healthcheck.sh --connect --innodb_initialized	Avoids mysqladmin-missing error; reuses same logic as Docker healthcheck

---

Validation Architecture

Test Framework

Property	Value
API unit tests	Vitest 4.1.x, config at apps/api/vitest.config.ts
API test command	pnpm --filter @familysync/api test (= vitest run)
PWA unit tests	Vitest (same framework), command pnpm --filter @familysync/pwa test
E2E harness	@playwright/test 1.60.0, config at apps/pwa/playwright.config.ts
E2E command	pnpm test:e2e (from root) = pnpm --filter @familysync/pwa test:e2e = playwright test

Phase Requirements → Test Map

Req ID	Behavior	Test Type	Automated Command	Exists?
CI-01	PR gate triggers on pull_request → main	workflow trigger test	Push a PR and observe	After W0
CI-01	lint passes	CI step	pnpm lint	✅
CI-01	typecheck both apps passes	CI step	pnpm typecheck	✅
CI-01	unit tests pass	CI step	pnpm test	✅
CI-01	API integration tests pass with MariaDB	CI step	pnpm --filter @familysync/api test + DB env	✅
CI-01	Playwright harness passes in CI	CI step	pnpm test:e2e with CI=true	✅ (Phase 7 specs)
CI-02	Docker image pushed to Gitea registry on merge	CI step	docker pull git.bergerhouse.net/luckberg/familysync-api:latest	After W2

Sampling Rate

• Per task commit (Wave 0): Run runner-probe workflow manually on branch; check Gitea Actions logs
• Per wave: Confirm all jobs in that wave pass on a test PR
• Phase gate: Full CI green on a real PR before /gsd-verify-work

Wave 0 Gaps

• .gitea/workflows/runner-probe.yml — runner probe workflow (new file; Wave 0 task)
• .gitea/workflows/ci.yml — main CI workflow (new file; Waves 1-2)

---

Security Domain

Applicable ASVS Categories

ASVS Category	Applies	Standard Control
V2 Authentication	no	Auth is not modified by this phase
V3 Session Management	no	Not modified
V4 Access Control	no	Not modified
V5 Input Validation	no	No new API endpoints
V6 Cryptography	yes (marginal)	PAT stored as Gitea repository secret; never in workflow YAML

Known Threat Patterns for CI/Docker

Pattern	STRIDE	Standard Mitigation
PAT in workflow YAML	Information Disclosure	Store as secrets.GITEA_REGISTRY_PAT; never echo or print
Docker socket mount (if runner uses it)	Elevation of Privilege	Known risk; accepted for Unraid self-hosted runner per Gitea docs
DB creds in CI env	Information Disclosure	Use throwaway test creds (not production DB_PASSWORD); never reuse production secrets
DEV_AUTH_BYPASS=true in CI	Spoofing	Only active in harness job; never bleeds to publish job; global-setup guard refuses NODE_ENV=production

---

Environment Availability

Dependency	Required By	Available	Version	Fallback
Gitea instance	All	✓	1.26.2	—
Gitea Actions runner	All	Unknown — 0 registered	Unknown	Must register runner before Phase 8 can proceed
Docker on runner	service containers, publish	Unknown	Unknown	Phase 8 is blocked without Docker on runner
Node.js 22 on runner	fast-checks, integration	Unknown	Unknown	actions/setup-node@v4 (probe P-01/P-08)
pnpm 11 on runner	All	Unknown	Unknown	corepack enable pnpm (probe P-02)
Internet access from runner	actions resolution, npm, Playwright install	Unknown	—	Probe P-07 confirms
Gitea registry PAT	CI-02	Not yet created	—	Operator must create before publish job

Missing dependencies with no fallback:

• Gitea Actions runner on Unraid (0 registered) — must be installed and registered before any CI runs
• Docker on runner — if absent, service containers and publish job both fail; no CI-relevant fallback

Missing dependencies with fallback:

• Node.js 22 — actions/setup-node@v4 installs it
• pnpm — corepack enable pnpm resolves it

---

Assumptions Log

#	Claim	Section	Risk if Wrong
A1	Runner is configured in Docker mode (not host mode)	Service Containers, Dev-Stack Bring-Up	Entire services: approach breaks; must pivot to docker run -d pattern
A2	actions/checkout@v4 and actions/setup-node@v4 resolve via DEFAULT_ACTIONS_URL=github.com	Standard Stack	CI fails at checkout; need to mirror or use absolute URLs
A3	actions/cache@v4 works without timeout in this runner's Docker network setup	Standard Stack	Cache steps time out; must remove and accept full install on every run
A4	ChristopherHX/gitea-upload-artifact@v4 uploads successfully to Gitea 1.26.2	Standard Stack	No artifact upload on failure; lose traces; manual debug only
A5	docker/login-action@v3 and docker/build-push-action@v6 resolve from GitHub	Standard Stack	Must use shell-level docker login + docker build/docker push instead
A6	reporter: 'github' produces invisible output in Gitea (not rendered as annotations)	Anti-Patterns	If Gitea DOES render them, the --reporter=list override is unnecessary but harmless
A7	GITHUB_SHA is available in Gitea Actions workflows	Image Tagging	Cannot compute short SHA via ${GITHUB_SHA:0:7}; must use git rev-parse --short HEAD
A8	Image name follows git.bergerhouse.net/luckberg/familysync-api convention	Registry Details	Push fails with 404; image name may need adjustment
A9	MariaDB --health-start-period=30s is sufficient for initialization	Patterns	Flaky health-check failures on slow runners; tune upward
A10	Playwright install --with-deps succeeds without root on runner	Dev-Stack Bring-Up	WebKit missing system libs; jobs fail with browser launch error

---

Open Questions

1. Runner mode: Docker vs host?

   • What we know: 0 runners are currently registered; no configuration is visible from outside
   • What's unclear: Whether the Unraid act_runner is/will be configured with Docker mode (service containers work) or host mode (service containers don't work)
   • Recommendation: Runner-probe task P-03 answers this definitively; plan must handle both branches

2. Unraid Docker socket access from act_runner container?

   • What we know: act_runner typically mounts /var/run/docker.sock to spawn job containers
   • What's unclear: Whether the Unraid act_runner installation (likely via Unraid Community Applications template) has the socket mount configured
   • Recommendation: Probe P-04 (docker info) answers this

3. actions/cache networking on this runner?

   • What we know: Known issue with act_runner's cache server networking in Docker mode
   • What's unclear: Whether the Gitea 1.26.2 + current act_runner release has fixed this
   • Recommendation: Probe P-09; design the cache step as continue-on-error: true or skip entirely

4. Playwright reporter: 'github' in Gitea — truly invisible?

   • What we know: Gitea does not document GitHub workflow command support
   • What's unclear: Whether Gitea 1.26.2 partially supports ::error:: annotation commands
   • Recommendation: Probe P-11 (upload artifact test) can also test reporter output; plan to override reporter to ['list', 'html'] as default

5. Milestone string automation — read from PROJECT.md or hardcode?

   • What we know: PROJECT.md says "Current Milestone: v1.1"; D-04 says "read from PROJECT.md if avoidable"
   • What's unclear: Whether the executor wants a grep step to extract v1.1 dynamically
   • Recommendation: Hardcode v1.1 as a workflow-level env var (MILESTONE: v1.1) for Wave 2; update it manually at milestone boundaries. Simpler than parsing.

---

Sources

Primary (HIGH confidence)

• Gitea container registry docs — registry host format, image naming, PAT auth requirement
• Gitea Actions comparison page — what is and isn't supported vs GitHub Actions
• Gitea Actions quickstart — .gitea/workflows/ location confirmed
• MariaDB healthcheck.sh docs — --connect --innodb_initialized options
• ChristopherHX/gitea-upload-artifact README — Gitea-compatible upload-artifact v4 fork
• Gitea issue #31256: upload-artifact@v4 not available — confirmed GHES detection block
• GitHub Actions: Communicating with service containers — host-mode vs container-mode networking semantics
• nektos/act issue #2711: service containers in host mode — host executor does NOT support service containers
• Gitea forum: proper container registry procedure — GITHUB_TOKEN fails; PAT required
• Gitea forum: GITHUB_SHA in Gitea Actions — GITHUB_SHA confirmed, ${hash::10} syntax confirmed
• mage-os issue: mysqladmin removed from mariadb:11 — confirmed mysqladmin absent from mariadb:11 image
• Playwright CI docs — --with-deps install, no-cache recommendation

Secondary (MEDIUM confidence)

• firefart.at: MySQL service with GitHub Actions — service container pattern when job runs on host (port mapping, 127.0.0.1)
• Gitea forum: service container not starting — evidence service containers are unreliable in some configurations; unresolved in forum
• Various community blog posts on Gitea Actions (chrisliebaer, botmonster) — cross-check on action resolution and registry

Tertiary (LOW confidence / ASSUMED)

• All items tagged [ASSUMED] in this document — confirmed via training knowledge + community reports but not directly verified against the Unraid act_runner; confirmed by runner-probe

---

Metadata

Confidence breakdown:

• Gitea Actions workflow syntax: HIGH — standard GitHub Actions YAML; confirmed supported
• Service containers: MEDIUM — Docker mode works per docs/act design; host mode does not; runner mode unknown
• MariaDB healthcheck: HIGH — confirmed in official docs and multiple issue threads
• Registry push / PAT auth: HIGH — confirmed in Gitea docs and forum
• actions/upload-artifact block on Gitea: HIGH — confirmed in Gitea issue tracker
• actions/cache networking: MEDIUM — known issue; unclear if fixed in current act_runner
• Playwright CI: HIGH — official Playwright docs are clear
• Short SHA syntax: HIGH — confirmed in Gitea forum

Research date: 2026-06-11 Valid until: 2026-09-11 (stable CI/tooling area; 90 days)