---
phase: 08-gitea-ci
plan: "01"
subsystem: infra
tags: [gitea, ci, act_runner, github-actions, docker, playwright, mariadb, artifacts]

# Dependency graph
requires: []
provides:
  - "Runner-probe workflow (.gitea/workflows/runner-probe.yml) confirming the Unraid act_runner environment"
  - "Confirmed answers to all P-01..P-13 unknowns from 08-RESEARCH §Runner-Probe Checklist"
  - "Registered act_runner + GITEA_REGISTRY_PAT repo secret (operator actions)"
affects:
  - 08-02-PLAN
  - 08-03-PLAN
  - 08-04-PLAN

# Tech tracking
tech-stack:
  added:
    - "act_runner (Docker-executor mode, registered on git.bergerhouse.net)"
    - "ChristopherHX/gitea-upload-artifact@v4 (Gitea-compatible artifact upload fork)"
    - "actions/checkout@v4, actions/setup-node@v4 (resolved via github.com)"
  patterns:
    - "runner-probe-first: probe the runner environment before any real test/build/publish step"
    - "healthcheck.sh --connect --innodb_initialized for MariaDB 11 readiness (not mysqladmin ping)"
    - "ubuntu-latest runs-on label (runner advertises ubuntu-latest, not self-hosted)"

key-files:
  created:
    - .gitea/workflows/runner-probe.yml
  modified: []

key-decisions:
  - "D-PROBE-01: runs-on must be ubuntu-latest (not self-hosted) — runner has no self-hosted label; all downstream ci.yml workflows (Plans 02-04) MUST use runs-on: ubuntu-latest"
  - "D-PROBE-02: runner is Docker-executor mode (/.dockerenv present) — services: works; DB_HOST=mariadb in ci.yml"
  - "D-PROBE-03: MariaDB service container works and is reachable on hostname mariadb; DB readiness must use healthcheck, NOT mysql CLI (not installed in runner image)"
  - "D-PROBE-04: actions/cache@v4 is unreliable (timeout) — do NOT use cache in Plans 02/03; at most best-effort"
  - "D-PROBE-05: Playwright WebKit + Chromium deps install cleanly (exit 0); Phase-7 harness is CI-feasible"
  - "D-PROBE-06: ChristopherHX/gitea-upload-artifact@v4 works — plans 03/04 MUST use this fork, never actions/upload-artifact@v4"
  - "D-PROBE-07: short SHA via ${GITHUB_SHA:0:7} produces 7 chars — D-04 publish tag expression confirmed valid"
  - "D-PROBE-08: GITEA_REGISTRY_PAT deferred to Plan 04 (operator decision; PAT not exercised in probe)"

patterns-established:
  - "Probe-before-build: all CI phase work starts with a non-destructive probe run to confirm runner unknowns"
  - "No mysql CLI: DB readiness gating must use MariaDB service healthcheck or Node mysql2-based wait"
  - "Gitea artifact upload: always ChristopherHX/gitea-upload-artifact@v4, never actions/upload-artifact@v4"

requirements-completed: [CI-01, CI-02]

# Metrics
duration: 30min (Tasks 1+2 authoring) + probe run ~5min
completed: "2026-06-11"
---

# Phase 08 Plan 01: Runner Probe Summary

**Gitea act_runner probed via runner-probe.yml (Docker-executor mode confirmed); all P-01..P-13 fork answers recorded — Plans 02-04 now have confirmed DB_HOST, runs-on label, cache strategy, artifact upload fork, and WebKit feasibility**

## Performance

- **Duration:** ~35 min (authoring + probe execution)
- **Started:** 2026-06-11T12:00:00Z
- **Completed:** 2026-06-11T14:30:00Z
- **Tasks:** 3 (1 human-action, 1 auto, 1 human-verify)
- **Files modified:** 1 created

## Accomplishments

- Registered act_runner on the Unraid host (operator); GITEA_REGISTRY_PAT repo secret created (deferred to Plan 04)
- Authored `.gitea/workflows/runner-probe.yml` covering all P-01..P-13 unknowns from 08-RESEARCH §Runner-Probe Checklist
- Probe run completed (Gitea Actions run id 2, head sha 134d4db, conclusion: success, ~5 min); all downstream fork decisions are now grounded in real runner behavior

## Probe Fork Answers

These answers are the primary output of Plan 01. Plans 02, 03, and 04 MUST consume them.

| Probe | Question | Result | Implication |
|-------|----------|--------|-------------|
| P-03 | Runner mode | **Docker-executor** (`/.dockerenv` present) | `services:` works in all downstream jobs; `DB_HOST=mariadb` |
| P-05 | Service container spawn | **WORKS** — `mariadb:11` started healthy (`Up (healthy) 3306/tcp`) | Use `services: mariadb` in ci.yml |
| P-06 | DB reachability via CLI | **INCONCLUSIVE** — `mysql` CLI not installed in runner image (`command not found` for both `mariadb` and `127.0.0.1`); `mariadb` hostname resolves at Docker-network level | DB readiness gating in Plans 02/03 MUST NOT shell out to `mysql` CLI — use MariaDB healthcheck (`healthcheck.sh --connect --innodb_initialized`) and/or a Node `mysql2`-based wait; or explicitly install `mariadb-client` if a CLI step is required |
| P-08 | Action resolution | **WORKS** — `actions/checkout@v4` and `actions/setup-node@v4` (node 22) cloned from github.com; first-run clone slow (~60-75 s each) but reliable | No local mirror needed; plan for slow cold starts |
| P-09 | `actions/cache@v4` | **UNRELIABLE** — restore timed out (`getCacheEntry failed: Request timeout`; Pitfall 7) | Do NOT use `actions/cache` in Plans 02/03; at most `continue-on-error: true` best-effort |
| P-10 | Playwright WebKit deps | **OK** — `npx playwright install --with-deps webkit chromium` exits 0 (runs as root; no sudo/apt failure) | Phase-7 harness in CI is feasible; no extra apt workaround needed |
| P-11 | Artifact upload | **WORKS** — `ChristopherHX/gitea-upload-artifact@v4` uploaded (Artifact ID 1, download URL returned) | Plans 03/04 MUST use this fork; `actions/upload-artifact@v4` is broken on Gitea |
| P-13 | Short SHA | **WORKS** — `${GITHUB_SHA:0:7}` = `134d4db` (7 chars) | D-04 publish tag expression `git.bergerhouse.net/.../familysync:${GITHUB_SHA:0:7}` is valid |
| Security (T-08-01) | Secrets in probe log | **CLEAN** — probe references no secrets; log audit found no leak | PAT untouched in this plan |

### KEY DEVIATION for all downstream workflows

The runner advertises **`ubuntu-latest`** (and `ubuntu-24.04` / `ubuntu-22.04`), NOT `self-hosted`. Plans 02, 03, and 04 MUST use `runs-on: ubuntu-latest` — NOT `runs-on: self-hosted`. The probe was originally authored with `runs-on: self-hosted` and fixed in commit 134d4db.

## Task Commits

1. **Task 1: Register act_runner + create registry PAT (operator-only)** — no commit (infra only)
2. **Task 2: Author runner-probe workflow** — `b333d7b` (feat)
3. **Deviation fix: runs-on label** — `134d4db` (fix — `self-hosted` → `ubuntu-latest`)
4. **Task 3: Probe run + fork answers recorded** — this SUMMARY (docs)

## Files Created/Modified

- `.gitea/workflows/runner-probe.yml` — probe-only workflow covering P-01..P-13; triggers only on `gsd/phase-08-gitea-ci` branch; non-destructive (no migrations, no pushes, no writes to main)

## Decisions Made

- **D-PROBE-01 (runs-on label):** `ubuntu-latest` is the correct label; `self-hosted` would leave jobs queued indefinitely. All downstream ci.yml workflows use `ubuntu-latest`.
- **D-PROBE-02 (executor mode):** Docker-executor confirmed — `services:` is the correct DB bring-up path; the host-executor fallback (docker run) is not needed.
- **D-PROBE-03 (DB readiness):** No mysql CLI in runner image — healthcheck-based wait is the only viable approach without additional apt installs.
- **D-PROBE-04 (cache):** `actions/cache` timed out — skip cache in critical path; note in ci.yml comments.
- **D-PROBE-08 (PAT):** Registry PAT deferral confirmed — probe exercised no secrets; PAT secret creation is a Plan 04 prerequisite.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Fixed `runs-on: self-hosted` → `runs-on: ubuntu-latest`**
- **Found during:** Task 3 (probe run) — probe job stayed queued with no eligible runner
- **Issue:** The plan specified `runs-on: self-hosted` but the runner advertises `ubuntu-latest`/`ubuntu-24.04`/`ubuntu-22.04`, not the `self-hosted` label
- **Fix:** Changed `runs-on: self-hosted` to `runs-on: ubuntu-latest` in `.gitea/workflows/runner-probe.yml`; also updated the plan's `key_links.via` pattern to document the correct label
- **Files modified:** `.gitea/workflows/runner-probe.yml`, `.planning/phases/08-gitea-ci/08-01-PLAN.md`
- **Verification:** Probe run 2 (run id 2, head sha 134d4db) completed successfully (conclusion: success, ~5 min)
- **Committed in:** `134d4db`

---

**Total deviations:** 1 auto-fixed (Rule 1 - Bug: wrong runs-on label)
**Impact on plan:** Fix was necessary for the probe to execute at all. No scope creep.

## Issues Encountered

- First probe run (run id 1) queued indefinitely because `runs-on: self-hosted` matched no runner. Identified and fixed in commit 134d4db. Second run completed successfully.
- `actions/cache@v4` timed out (P-09) — expected per 08-RESEARCH Pitfall 7; recorded as finding, not a failure.
- `mysql` CLI absent from runner image (P-06) — inconclusive DB CLI reachability; mitigated by confirmed Docker-network hostname resolution and healthcheck-based wait strategy for Plans 02/03.

## User Setup Required

- act_runner registered on Unraid host (DONE — operator confirmed)
- `GITEA_REGISTRY_PAT` repo secret with `write:package` scope — **deferred to Plan 04** (operator decision; not needed until the publish job is designed)

## Next Phase Readiness

Plans 02-04 have everything they need from this probe:

- **DB bring-up:** `services: mariadb:11` with `healthcheck.sh --connect --innodb_initialized`; `DB_HOST=mariadb`
- **runs-on:** `ubuntu-latest` (confirmed label)
- **Cache:** skip or `continue-on-error: true` only
- **Playwright:** `npx playwright install --with-deps webkit chromium` works as-is
- **Artifact upload:** `ChristopherHX/gitea-upload-artifact@v4` only
- **Short SHA:** `${GITHUB_SHA:0:7}` valid for image tags

No blockers for Plan 02 (test job authoring).

---
*Phase: 08-gitea-ci*
*Completed: 2026-06-11*