From 3b05260323f25e75b3e38c1977f9f01ed43cd547 Mon Sep 17 00:00:00 2001
From: Brian Bjarke Jensen <bbj@skov.dk>
Date: Thu, 9 Jul 2026 22:21:22 +0200
Subject: [PATCH 1/4] Add nightly CI base image and migrate workflows to
 python-repositories-ci.

Pre-build Python, uv, and locked deps in a Gitea container image so daily jobs skip repeated bootstrap; document runner registry auth and ci-bot credentials.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .dockerignore                              |  16 +++
 .gitea/workflows/ci-image.yml              |  52 ++++++++
 .gitea/workflows/code-quality.yml          |  16 +--
 .gitea/workflows/dependency-update-bot.yml |  13 +-
 .gitea/workflows/publish.yml               |  19 ++-
 .gitea/workflows/release.yml               |  15 +--
 .gitea/workflows/security-audit.yml        |  16 +--
 .gitea/workflows/test.yml                  |  48 +++-----
 README.md                                  |   9 +-
 docker/ci/Dockerfile                       |  28 +++++
 docs/ci-image.md                           | 135 +++++++++++++++++++++
 11 files changed, 281 insertions(+), 86 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 .gitea/workflows/ci-image.yml
 create mode 100644 docker/ci/Dockerfile
 create mode 100644 docs/ci-image.md

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..e62379f
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,16 @@
+.git
+.github
+.gitea
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+__pycache__
+*.pyc
+.coverage
+coverage-unit
+coverage-integration
+coverage.txt
+dist
+build
+*.egg-info
diff --git a/.gitea/workflows/ci-image.yml b/.gitea/workflows/ci-image.yml
new file mode 100644
index 0000000..6264980
--- /dev/null
+++ b/.gitea/workflows/ci-image.yml
@@ -0,0 +1,52 @@
+# Build and publish the per-repo CI base image to the Gitea container registry.
+
+name: Build CI Image
+
+on:
+  schedule:
+    - cron: "0 2 * * *"
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - pyproject.toml
+      - uv.lock
+      - docker/ci/**
+
+env:
+  REGISTRY: gitea.lille-vemmelund.dk
+  REGISTRY_USER: ci-bot
+  IMAGE: gitea.lille-vemmelund.dk/brian/python-repositories-ci
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Log in to Gitea container registry
+        env:
+          CI_RUNNER_TOKEN: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: |
+          echo "$CI_RUNNER_TOKEN" | docker login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin
+
+      - name: Build CI image
+        env:
+          CI_RUNNER_TOKEN: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: |
+          echo "$CI_RUNNER_TOKEN" > /tmp/uv_token
+          docker build -f docker/ci/Dockerfile \
+            --secret id=uv_token,src=/tmp/uv_token \
+            -t "${IMAGE}:latest" \
+            .
+          rm -f /tmp/uv_token
+
+      - name: Tag and push CI image
+        run: |
+          STAMP="$(date -u +%Y%m%d%H%M)"
+          docker tag "${IMAGE}:latest" "${IMAGE}:${STAMP}"
+          docker push "${IMAGE}:latest"
+          docker push "${IMAGE}:${STAMP}"
+          echo "Pushed ${IMAGE}:latest and ${IMAGE}:${STAMP}"
diff --git a/.gitea/workflows/code-quality.yml b/.gitea/workflows/code-quality.yml
index 62dd616..cae05a8 100644
--- a/.gitea/workflows/code-quality.yml
+++ b/.gitea/workflows/code-quality.yml
@@ -8,23 +8,17 @@ on:
 
 jobs:
   code-quality:
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
-      - name: Install dependencies
+      - name: Sync dependencies
         env:
           UV_LINK_MODE: copy
-        run: uv sync --all-extras
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: uv sync --all-extras --frozen
 
       - name: Type check with mypy
         run: uv run mypy .
diff --git a/.gitea/workflows/dependency-update-bot.yml b/.gitea/workflows/dependency-update-bot.yml
index 421b04a..041c511 100644
--- a/.gitea/workflows/dependency-update-bot.yml
+++ b/.gitea/workflows/dependency-update-bot.yml
@@ -7,22 +7,17 @@ on:
 
 jobs:
   update-check:
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           token: ${{ secrets.CI_RUNNER_TOKEN }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
       - name: Upgrade dependencies
+        env:
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: uv lock --upgrade
 
       - name: Commit and push changes
diff --git a/.gitea/workflows/publish.yml b/.gitea/workflows/publish.yml
index 4a406f1..6ef6ad9 100644
--- a/.gitea/workflows/publish.yml
+++ b/.gitea/workflows/publish.yml
@@ -9,25 +9,24 @@ on:
 
 jobs:
   build-and-publish:
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
       - name: Update version in pyproject.toml to match tag
+        env:
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: scripts/ci/bump-version.sh --from-tag "${GITHUB_REF##*/}"
 
       - name: Build package
+        env:
+          UV_LINK_MODE: copy
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: |
-          uv sync --no-dev
+          uv sync --no-dev --frozen
           uv build
 
       - name: Publish to Gitea Package Registry
diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml
index 17b8a63..4b8890c 100644
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -8,7 +8,7 @@ on:
 jobs:
   release:
     if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -22,19 +22,12 @@ jobs:
           COMMIT_MSG: ${{ github.event.head_commit.message }}
         run: scripts/ci/parse-merge-commit.sh "$COMMIT_MSG"
 
-      - name: Set up Python
-        if: steps.meta.outputs.bump != 'skip'
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        if: steps.meta.outputs.bump != 'skip'
-        run: pip install uv
-
       - name: Bump version
         if: steps.meta.outputs.bump != 'skip'
         id: bump
+        env:
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: scripts/ci/bump-version.sh "${{ steps.meta.outputs.bump }}"
 
       - name: Generate release notes
diff --git a/.gitea/workflows/security-audit.yml b/.gitea/workflows/security-audit.yml
index 37d3395..5d4a926 100644
--- a/.gitea/workflows/security-audit.yml
+++ b/.gitea/workflows/security-audit.yml
@@ -7,23 +7,17 @@ on:
 
 jobs:
   safety:
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
-      - name: Install dependencies
+      - name: Sync dependencies
         env:
           UV_LINK_MODE: copy
-        run: uv sync
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: uv sync --frozen
 
       - name: Run safety check
         run: uv run safety check
diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml
index 43376f7..adb46f1 100644
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -8,23 +8,17 @@ on:
 
 jobs:
   unit-tests:
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
-      - name: Install dependencies
+      - name: Sync dependencies
         env:
           UV_LINK_MODE: copy
-        run: uv sync --all-extras
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: uv sync --all-extras --frozen
 
       - name: Run unit tests
         run: |
@@ -43,23 +37,17 @@ jobs:
           compression-level: 0
 
   integration-tests:
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
-      - name: Install dependencies
+      - name: Sync dependencies
         env:
           UV_LINK_MODE: copy
-        run: uv sync --all-extras
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: uv sync --all-extras --frozen
 
       - name: Verify Docker
         run: docker info
@@ -83,24 +71,18 @@ jobs:
   coverage-report:
     # Merges unit + integration coverage and enforces fail_under from pyproject.toml.
     needs: [unit-tests, integration-tests]
-    runs-on: ubuntu-latest
+    runs-on: python-repositories-ci
     if: github.event_name == 'pull_request' || github.event_name == 'push'
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
-
-      - name: Install uv
-        run: pip install uv
-
-      - name: Install dependencies
+      - name: Sync dependencies
         env:
           UV_LINK_MODE: copy
-        run: uv sync --all-extras
+          UV_INDEX_GITEA_USERNAME: ci-bot
+          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
+        run: uv sync --all-extras --frozen
 
       - name: Download unit coverage
         uses: https://github.com/christopherHX/gitea-download-artifact@v4
diff --git a/README.md b/README.md
index 32d3623..274efe8 100644
--- a/README.md
+++ b/README.md
@@ -166,7 +166,14 @@ uv run pytest -v                                      # full suite (requires Doc
 
 Integration tests are marked with `@pytest.mark.integration` and require Docker (testcontainers). Run unit tests alone for quick local feedback.
 
-CI runs unit and integration tests in parallel with coverage, then merges `.coverage` artifacts in a follow-up job (via [christopherhx/gitea-\*-artifact@v4](https://github.com/christopherHX/gitea-upload-artifact) for Gitea 1.26 compatibility). Combined coverage must be at least **90%**; the floor is set by [`fail_under` in `pyproject.toml`](pyproject.toml#L45-L48) and enforced after merging unit and integration coverage, not on unit-only runs.
+### CI base image
+
+Gitea Actions jobs use a pre-built image (`python-repositories-ci`) with Python 3.12,
+`uv`, and locked dependencies baked in. The image is rebuilt nightly and when
+`uv.lock` changes; see [`docs/ci-image.md`](docs/ci-image.md) for runner setup and
+bootstrap order.
+
+CI runs unit and integration tests in parallel with coverage, then merges `.coverage` artifacts in a follow-up job (via [christopherhx/gitea-\*-artifact@v4](https://github.com/christopherHX/gitea-upload-artifact) for Gitea 1.26 compatibility). Combined coverage must meet the floor in [`fail_under` in `pyproject.toml`](pyproject.toml#L45-L48); enforcement happens after merging unit and integration coverage, not on unit-only runs.
 
 To check coverage locally (requires Docker for the full suite):
 
diff --git a/docker/ci/Dockerfile b/docker/ci/Dockerfile
new file mode 100644
index 0000000..c66967d
--- /dev/null
+++ b/docker/ci/Dockerfile
@@ -0,0 +1,28 @@
+# CI job image for Gitea Actions (act_runner requires Node.js in job containers).
+FROM node:20-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        docker.io \
+        git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.7.0 /uv /usr/local/bin/uv
+
+ENV UV_PYTHON_INSTALL_DIR=/opt/uv-python \
+    UV_PYTHON=3.12 \
+    UV_LINK_MODE=copy \
+    PATH="/app/.venv/bin:${PATH}"
+
+RUN uv python install 3.12
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock .python-version ./
+
+RUN --mount=type=secret,id=uv_token \
+    UV_INDEX_GITEA_USERNAME=ci-bot \
+    UV_INDEX_GITEA_PASSWORD="$(cat /run/secrets/uv_token)" \
+    uv sync --all-extras --frozen --no-install-project
diff --git a/docs/ci-image.md b/docs/ci-image.md
new file mode 100644
index 0000000..b127c18
--- /dev/null
+++ b/docs/ci-image.md
@@ -0,0 +1,135 @@
+# CI base image
+
+This repository uses a **per-repo Docker image** for Gitea Actions jobs instead of
+installing Python and `uv` on every run. Infrastructure images (redis, minio, etc.)
+are cached cluster-wide via Harbor (see homelab-platform
+[`docs/harbor-registry-mirror.md`](https://gitea.lille-vemmelund.dk/LilleVemmelund/homelab-platform/src/branch/main/docs/harbor-registry-mirror.md)).
+
+## Image contents
+
+Built from [`docker/ci/Dockerfile`](../docker/ci/Dockerfile):
+
+- Node.js 20 (required by act_runner job containers)
+- Python 3.12 (installed via `uv python install`) and pinned `uv` 0.7.0
+- Docker CLI (integration tests via testcontainers)
+- Dev dependencies from `uv.lock` (`uv sync --all-extras --no-install-project`)
+
+Published to the Gitea container registry:
+
+- `gitea.lille-vemmelund.dk/brian/python-repositories-ci:latest`
+- `gitea.lille-vemmelund.dk/brian/python-repositories-ci:YYYYMMDDHHmm` (timestamped rollback tag)
+
+## Rebuild triggers
+
+[`ci-image.yml`](../.gitea/workflows/ci-image.yml) runs on:
+
+- Nightly cron (`0 2 * * *` UTC)
+- Manual `workflow_dispatch`
+- Push to `main` when `pyproject.toml`, `uv.lock`, or `docker/ci/**` change
+
+## Workflow usage
+
+Python jobs use `runs-on: python-repositories-ci` and a fast incremental sync:
+
+```yaml
+runs-on: python-repositories-ci
+steps:
+  - uses: actions/checkout@v4
+  - name: Sync dependencies
+    env:
+      UV_LINK_MODE: copy
+      UV_INDEX_GITEA_USERNAME: ci-bot
+      UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
+    run: uv sync --all-extras --frozen
+```
+
+`ci-image.yml` uses `runs-on: ubuntu-latest` so it can bootstrap before the custom
+image exists.
+
+## Registry authentication
+
+act_runner pulls the job image **before any workflow step runs**, so a `docker
+login` step inside a job cannot authenticate that pull. Authentication must be
+configured on the runner (or via a job-level `container.credentials` block — not
+used here).
+
+### k8s Gitea runners (automatic)
+
+The homelab-platform runners mount Gitea registry credentials automatically:
+
+- Secret: `gitea-runners/gitea-registry-dockerconfig` (created by
+  [`scripts/create-gitea-registry-secret.sh`](https://gitea.lille-vemmelund.dk/LilleVemmelund/homelab-platform/src/branch/main/scripts/create-gitea-registry-secret.sh))
+- Mounted at `/root/.docker/config.json` on the **runner** container (not DinD)
+- Configured in
+  [`platform/gitea-runners/values.yaml`](https://gitea.lille-vemmelund.dk/LilleVemmelund/homelab-platform/src/branch/main/platform/gitea-runners/values.yaml)
+
+No manual `docker login` is required on the in-cluster runners once the secret
+exists. To create or rotate credentials:
+
+```bash
+export KUBECONFIG=/path/to/homelab-cluster/talos/_out/kubeconfig
+export GITEA_REGISTRY_USERNAME='ci-bot'
+export GITEA_REGISTRY_PASSWORD='personal-access-token-with-read-package'
+bash scripts/create-gitea-registry-secret.sh
+```
+
+Then restart runner pods so they pick up the updated secret. See homelab-platform
+[`docs/gitea-actions-runners.md`](https://gitea.lille-vemmelund.dk/LilleVemmelund/homelab-platform/src/branch/main/docs/gitea-actions-runners.md)
+for full runner setup.
+
+Verify on a running pod:
+
+```bash
+kubectl -n gitea-runners exec homelab-cluster-gitea-runner-0 -c runner -- \
+  test -f /root/.docker/config.json && echo "registry auth mounted"
+```
+
+### Standalone runners (e.g. Unraid `homelab`)
+
+The 4th runner is outside the k8s cluster and does **not** get the automatic
+mount. Configure registry auth manually on that host:
+
+```bash
+docker login gitea.lille-vemmelund.dk -u ci-bot -p <token>
+```
+
+Also add the `python-repositories-ci` label to that runner's act_runner config.
+
+### `ci-image.yml` push login
+
+The build workflow still runs `docker login` before `docker push`. That step
+authenticates **DinD inside the job** for pushing the image to Gitea — a different
+code path from act_runner pulling the job container.
+
+## Runner label
+
+Jobs use the `python-repositories-ci` act_runner label, configured in
+homelab-platform
+[`platform/gitea-runners/values.yaml`](https://gitea.lille-vemmelund.dk/LilleVemmelund/homelab-platform/src/branch/main/platform/gitea-runners/values.yaml):
+
+```yaml
+python-repositories-ci:docker://gitea.lille-vemmelund.dk/brian/python-repositories-ci:latest
+```
+
+After label changes, roll runner pods so they re-register with Gitea.
+
+## Bootstrap order
+
+1. Ensure homelab-platform runners have `gitea-registry-dockerconfig` and the
+   `python-repositories-ci` label (see homelab-platform docs).
+2. Merge `ci-image.yml`, `docker/ci/Dockerfile`, and workflow migrations to `main`.
+3. Run **Build CI Image** manually once (Actions → Build CI Image → Run workflow).
+4. Confirm a test workflow job starts on `python-repositories-ci`.
+
+Until step 3 completes, jobs targeting `python-repositories-ci` will fail because
+the image does not exist in the Gitea registry yet.
+
+## Local build
+
+```bash
+echo "$CI_RUNNER_TOKEN" > /tmp/uv_token
+docker build -f docker/ci/Dockerfile \
+  --secret id=uv_token,src=/tmp/uv_token \
+  -t python-repositories-ci:local .
+rm -f /tmp/uv_token
+```

From f2a8581de2d8a4151406ff2a9eca3449c6beeef3 Mon Sep 17 00:00:00 2001
From: Brian Bjarke Jensen <bbj@skov.dk>
Date: Thu, 9 Jul 2026 22:27:59 +0200
Subject: [PATCH 2/4] Read Python version from .python-version in CI image
 build.

Avoid hardcoding 3.12 in the Dockerfile so the CI image tracks the same source of truth as local tooling and uv sync.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docker/ci/Dockerfile | 9 +++++----
 docs/ci-image.md     | 2 +-
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/docker/ci/Dockerfile b/docker/ci/Dockerfile
index c66967d..35762c8 100644
--- a/docker/ci/Dockerfile
+++ b/docker/ci/Dockerfile
@@ -12,16 +12,17 @@ RUN apt-get update \
 COPY --from=ghcr.io/astral-sh/uv:0.7.0 /uv /usr/local/bin/uv
 
 ENV UV_PYTHON_INSTALL_DIR=/opt/uv-python \
-    UV_PYTHON=3.12 \
-    UV_LINK_MODE=copy \
-    PATH="/app/.venv/bin:${PATH}"
+    UV_LINK_MODE=copy
 
-RUN uv python install 3.12
+COPY .python-version /tmp/.python-version
+RUN uv python install "$(cat /tmp/.python-version)"
 
 WORKDIR /app
 
 COPY pyproject.toml uv.lock .python-version ./
 
+ENV PATH="/app/.venv/bin:${PATH}"
+
 RUN --mount=type=secret,id=uv_token \
     UV_INDEX_GITEA_USERNAME=ci-bot \
     UV_INDEX_GITEA_PASSWORD="$(cat /run/secrets/uv_token)" \
diff --git a/docs/ci-image.md b/docs/ci-image.md
index b127c18..cbbc386 100644
--- a/docs/ci-image.md
+++ b/docs/ci-image.md
@@ -10,7 +10,7 @@ are cached cluster-wide via Harbor (see homelab-platform
 Built from [`docker/ci/Dockerfile`](../docker/ci/Dockerfile):
 
 - Node.js 20 (required by act_runner job containers)
-- Python 3.12 (installed via `uv python install`) and pinned `uv` 0.7.0
+- Python 3.12 (installed via `uv python install` from [`.python-version`](../.python-version)) and pinned `uv` 0.7.0
 - Docker CLI (integration tests via testcontainers)
 - Dev dependencies from `uv.lock` (`uv sync --all-extras --no-install-project`)
 

From 441a21204dbe272ffc9c2c2cbb8c24d20641d5c4 Mon Sep 17 00:00:00 2001
From: Brian Bjarke Jensen <bbj@skov.dk>
Date: Thu, 9 Jul 2026 22:39:33 +0200
Subject: [PATCH 3/4] Add local CI image build script and document bootstrap
 flow.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/ci-image.md             | 36 ++++++++++++++++-
 scripts/ci/build-ci-image.sh | 78 ++++++++++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+), 1 deletion(-)
 create mode 100755 scripts/ci/build-ci-image.sh

diff --git a/docs/ci-image.md b/docs/ci-image.md
index cbbc386..5380c24 100644
--- a/docs/ci-image.md
+++ b/docs/ci-image.md
@@ -118,14 +118,48 @@ After label changes, roll runner pods so they re-register with Gitea.
 1. Ensure homelab-platform runners have `gitea-registry-dockerconfig` and the
    `python-repositories-ci` label (see homelab-platform docs).
 2. Merge `ci-image.yml`, `docker/ci/Dockerfile`, and workflow migrations to `main`.
-3. Run **Build CI Image** manually once (Actions → Build CI Image → Run workflow).
+3. Seed the registry with a first image (see below).
 4. Confirm a test workflow job starts on `python-repositories-ci`.
 
 Until step 3 completes, jobs targeting `python-repositories-ci` will fail because
 the image does not exist in the Gitea registry yet.
 
+### Seed the image
+
+**After merge to `main`:** Actions → **Build CI Image** → **Run workflow**.
+
+**Before merge (e.g. PR branch):** the workflow file is not on `main` yet — build
+and push locally with [`scripts/ci/build-ci-image.sh`](../scripts/ci/build-ci-image.sh):
+
+```bash
+export CI_RUNNER_TOKEN='ci-bot-personal-access-token'
+bash scripts/ci/build-ci-image.sh --push
+```
+
+Run from the repo root on the branch you want to test. Runners pull
+`gitea.lille-vemmelund.dk/brian/python-repositories-ci:latest` from the registry;
+they do not care which git branch built it.
+
+Override registry settings if needed:
+
+```bash
+export REGISTRY=gitea.lille-vemmelund.dk
+export REGISTRY_USER=ci-bot
+export CI_RUNNER_TOKEN='...'
+bash scripts/ci/build-ci-image.sh --push
+```
+
 ## Local build
 
+Build only (no registry login or push):
+
+```bash
+export CI_RUNNER_TOKEN='ci-bot-personal-access-token'
+bash scripts/ci/build-ci-image.sh --local
+```
+
+Or manually:
+
 ```bash
 echo "$CI_RUNNER_TOKEN" > /tmp/uv_token
 docker build -f docker/ci/Dockerfile \
diff --git a/scripts/ci/build-ci-image.sh b/scripts/ci/build-ci-image.sh
new file mode 100755
index 0000000..7c0f3cc
--- /dev/null
+++ b/scripts/ci/build-ci-image.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Build and optionally push the Gitea Actions CI base image locally.
+#
+# Use when ci-image.yml is not yet on main (e.g. bootstrapping a PR branch) or
+# when you need to rebuild without waiting for the nightly workflow.
+#
+# Build only (smoke test):
+#   export CI_RUNNER_TOKEN='ci-bot-personal-access-token'
+#   bash scripts/ci/build-ci-image.sh --local
+#
+# Build and push to Gitea (unblocks python-repositories-ci jobs):
+#   export CI_RUNNER_TOKEN='ci-bot-personal-access-token'
+#   bash scripts/ci/build-ci-image.sh --push
+#
+# Optional overrides:
+#   REGISTRY=gitea.lille-vemmelund.dk
+#   REGISTRY_USER=ci-bot
+#   IMAGE_OWNER=brian
+#   IMAGE_NAME=python-repositories-ci
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+REGISTRY="${REGISTRY:-gitea.lille-vemmelund.dk}"
+REGISTRY_USER="${REGISTRY_USER:-ci-bot}"
+IMAGE_OWNER="${IMAGE_OWNER:-brian}"
+IMAGE_NAME="${IMAGE_NAME:-python-repositories-ci}"
+IMAGE="${IMAGE:-${REGISTRY}/${IMAGE_OWNER}/${IMAGE_NAME}}"
+
+MODE="push"
+if [[ "${1:-}" == "--local" ]]; then
+  MODE="local"
+elif [[ "${1:-}" == "--push" || -z "${1:-}" ]]; then
+  MODE="push"
+elif [[ -n "${1:-}" ]]; then
+  echo "Usage: build-ci-image.sh [--local | --push]" >&2
+  exit 1
+fi
+
+: "${CI_RUNNER_TOKEN:?CI_RUNNER_TOKEN is required (ci-bot token with read/write package access)}"
+
+TOKEN_FILE="$(mktemp)"
+cleanup() {
+  rm -f "$TOKEN_FILE"
+}
+trap cleanup EXIT
+
+printf '%s' "$CI_RUNNER_TOKEN" >"$TOKEN_FILE"
+
+cd "$REPO_ROOT"
+
+if [[ "$MODE" == "local" ]]; then
+  echo "=== Building local CI image (no push): python-repositories-ci:local ==="
+  docker build -f docker/ci/Dockerfile \
+    --secret "id=uv_token,src=${TOKEN_FILE}" \
+    -t python-repositories-ci:local \
+    .
+  echo "Built python-repositories-ci:local"
+  exit 0
+fi
+
+echo "=== Logging in to ${REGISTRY} as ${REGISTRY_USER} ==="
+echo "$CI_RUNNER_TOKEN" | docker login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin
+
+echo "=== Building ${IMAGE}:latest ==="
+docker build -f docker/ci/Dockerfile \
+  --secret "id=uv_token,src=${TOKEN_FILE}" \
+  -t "${IMAGE}:latest" \
+  .
+
+STAMP="$(date -u +%Y%m%d%H%M)"
+echo "=== Pushing ${IMAGE}:latest and ${IMAGE}:${STAMP} ==="
+docker tag "${IMAGE}:latest" "${IMAGE}:${STAMP}"
+docker push "${IMAGE}:latest"
+docker push "${IMAGE}:${STAMP}"
+
+echo "Done. Re-run failing CI jobs — runners pull ${IMAGE}:latest"

From b21fd247c569dc47e04eb0b815d4d81b69f6d464 Mon Sep 17 00:00:00 2001
From: Brian Bjarke Jensen <bbj@skov.dk>
Date: Thu, 9 Jul 2026 22:47:52 +0200
Subject: [PATCH 4/4] Revert workflows to ubuntu-latest until CI image is
 seeded.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .gitea/workflows/code-quality.yml          | 16 +++++---
 .gitea/workflows/dependency-update-bot.yml | 13 ++++--
 .gitea/workflows/publish.yml               | 19 +++++----
 .gitea/workflows/release.yml               | 15 +++++--
 .gitea/workflows/security-audit.yml        | 16 +++++---
 .gitea/workflows/test.yml                  | 48 +++++++++++++++-------
 6 files changed, 85 insertions(+), 42 deletions(-)

diff --git a/.gitea/workflows/code-quality.yml b/.gitea/workflows/code-quality.yml
index cae05a8..62dd616 100644
--- a/.gitea/workflows/code-quality.yml
+++ b/.gitea/workflows/code-quality.yml
@@ -8,17 +8,23 @@ on:
 
 jobs:
   code-quality:
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Sync dependencies
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
         env:
           UV_LINK_MODE: copy
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
-        run: uv sync --all-extras --frozen
+        run: uv sync --all-extras
 
       - name: Type check with mypy
         run: uv run mypy .
diff --git a/.gitea/workflows/dependency-update-bot.yml b/.gitea/workflows/dependency-update-bot.yml
index 041c511..421b04a 100644
--- a/.gitea/workflows/dependency-update-bot.yml
+++ b/.gitea/workflows/dependency-update-bot.yml
@@ -7,17 +7,22 @@ on:
 
 jobs:
   update-check:
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           token: ${{ secrets.CI_RUNNER_TOKEN }}
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
       - name: Upgrade dependencies
-        env:
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: uv lock --upgrade
 
       - name: Commit and push changes
diff --git a/.gitea/workflows/publish.yml b/.gitea/workflows/publish.yml
index 6ef6ad9..4a406f1 100644
--- a/.gitea/workflows/publish.yml
+++ b/.gitea/workflows/publish.yml
@@ -9,24 +9,25 @@ on:
 
 jobs:
   build-and-publish:
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
       - name: Update version in pyproject.toml to match tag
-        env:
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: scripts/ci/bump-version.sh --from-tag "${GITHUB_REF##*/}"
 
       - name: Build package
-        env:
-          UV_LINK_MODE: copy
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: |
-          uv sync --no-dev --frozen
+          uv sync --no-dev
           uv build
 
       - name: Publish to Gitea Package Registry
diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml
index 4b8890c..17b8a63 100644
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -8,7 +8,7 @@ on:
 jobs:
   release:
     if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -22,12 +22,19 @@ jobs:
           COMMIT_MSG: ${{ github.event.head_commit.message }}
         run: scripts/ci/parse-merge-commit.sh "$COMMIT_MSG"
 
+      - name: Set up Python
+        if: steps.meta.outputs.bump != 'skip'
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        if: steps.meta.outputs.bump != 'skip'
+        run: pip install uv
+
       - name: Bump version
         if: steps.meta.outputs.bump != 'skip'
         id: bump
-        env:
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
         run: scripts/ci/bump-version.sh "${{ steps.meta.outputs.bump }}"
 
       - name: Generate release notes
diff --git a/.gitea/workflows/security-audit.yml b/.gitea/workflows/security-audit.yml
index 5d4a926..37d3395 100644
--- a/.gitea/workflows/security-audit.yml
+++ b/.gitea/workflows/security-audit.yml
@@ -7,17 +7,23 @@ on:
 
 jobs:
   safety:
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Sync dependencies
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
         env:
           UV_LINK_MODE: copy
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
-        run: uv sync --frozen
+        run: uv sync
 
       - name: Run safety check
         run: uv run safety check
diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml
index adb46f1..43376f7 100644
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -8,17 +8,23 @@ on:
 
 jobs:
   unit-tests:
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Sync dependencies
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
         env:
           UV_LINK_MODE: copy
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
-        run: uv sync --all-extras --frozen
+        run: uv sync --all-extras
 
       - name: Run unit tests
         run: |
@@ -37,17 +43,23 @@ jobs:
           compression-level: 0
 
   integration-tests:
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Sync dependencies
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
         env:
           UV_LINK_MODE: copy
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
-        run: uv sync --all-extras --frozen
+        run: uv sync --all-extras
 
       - name: Verify Docker
         run: docker info
@@ -71,18 +83,24 @@ jobs:
   coverage-report:
     # Merges unit + integration coverage and enforces fail_under from pyproject.toml.
     needs: [unit-tests, integration-tests]
-    runs-on: python-repositories-ci
+    runs-on: ubuntu-latest
     if: github.event_name == 'pull_request' || github.event_name == 'push'
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Sync dependencies
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
         env:
           UV_LINK_MODE: copy
-          UV_INDEX_GITEA_USERNAME: ci-bot
-          UV_INDEX_GITEA_PASSWORD: ${{ secrets.CI_RUNNER_TOKEN }}
-        run: uv sync --all-extras --frozen
+        run: uv sync --all-extras
 
       - name: Download unit coverage
         uses: https://github.com/christopherHX/gitea-download-artifact@v4