ci: docker-build lifecycle hardening — PR build-without-push, no-cache, weekly refresh

The image lifecycle was the review's weakest subsystem. Three additions to
docker-build.yml, none changing the normal push path:

- pull_request trigger scoped to .github/docker/** and this workflow: builds
  the image to validate a Dockerfile change before merge, WITHOUT pushing (the
  login step is skipped and push: is false via github.event_name), so a fork
  PR never touches the packages:write token. params derives the series from
  github.base_ref on a PR.

- workflow_dispatch 'no-cache' boolean input wired to build-push-action, for a
  from-scratch rebuild that picks up base-image/apt and new gramps patch
  releases the buildx cache key would otherwise skip.

- weekly schedule + a weekly-rebuild fan-out job that dispatches a no-cache
  rebuild per maintenance branch (permissions: actions: write; existing job
  guarded off schedule). Documented as inert until the workflows reach the
  default branch, since scheduled runs fire only from there.

CI-MAINTAINER.md gains an 'Image lifecycle' section covering all of the above
plus the known one-push image lag (ci.yml pulls the moving tag while the
rebuild runs, so an image-affecting push tests against the previous image —
re-run the affected jobs after the build; the Dockerfile ruff pin lands one
push late for the same reason).

Author: eduralph

.github/CI-MAINTAINER.md

@@ -14,8 +14,9 @@ an unreleased branch see [CONTRIBUTING.md](../CONTRIBUTING.md#work-towards-a-mer
 1. [One-time setup when the PR first merges](#one-time-setup-when-the-pr-first-merges)
 2. [Creating a new maintenance branch](#creating-a-new-maintenance-branch)
 3. [When a Gramps minor release lands on PyPI](#when-a-gramps-minor-release-lands-on-pypi)
-4. [Diagnostic log markers](#diagnostic-log-markers)
-5. [Optional future-proofing knobs](#optional-future-proofing-knobs)
+4. [Image lifecycle](#image-lifecycle)
+5. [Diagnostic log markers](#diagnostic-log-markers)
+6. [Optional future-proofing knobs](#optional-future-proofing-knobs)
 
 ## One-time setup when the PR first merges
 
@@ -109,6 +110,39 @@ waiting for the next push:
 
 The `::notice::` line in the build log confirms the switch.
 
+## Image lifecycle
+
+`docker-build.yml` owns the `gramps-ci:<suffix>` image. How it rebuilds:
+
+- **On push** to `maintenance/gramps**` — builds and pushes the image
+  for that branch. This is the normal path.
+- **On pull_request** touching `.github/docker/**` or
+  `docker-build.yml` — builds the image **without pushing** (the login
+  step is skipped and `push:` is false), so a Dockerfile change is
+  validated before merge. A fork PR never touches the push credential.
+  A green PR build proves "the image still builds"; it does **not**
+  update the tag CI pulls.
+- **workflow_dispatch** with **`no-cache: true`** — a from-scratch
+  rebuild that ignores the buildx layer cache. Use this to pick up a
+  new base-image (apt security) update or a newly published gramps
+  patch release that the cache key would otherwise skip.
+- **Weekly `schedule`** — the `weekly-rebuild` job fans out a
+  `no-cache` dispatch to every `maintenance/grampsNN` branch.
+  **Caveat:** GitHub runs scheduled workflows only from the repo's
+  **default branch**, so this is inert until these workflows exist
+  there (upstream's default is `maintenance/gramps61`). That is by
+  design — remove/adjust it if the default branch never carries the
+  pipeline.
+
+**Known one-push image lag (not fixed, be aware):** `ci.yml` and
+`docker-build.yml` both fire on the same push, and `ci.yml` pulls the
+moving `gramps-ci:<suffix>` tag while the rebuild is still running. So a
+push that changes the image (e.g. a Dockerfile edit) has its CI run
+against the **previous** image. After the `Build Docker Images` run for
+that push finishes, **re-run the affected CI jobs** to test against the
+new image. For the same reason, the `ruff` version pinned in the
+Dockerfile takes effect one push late.
+
 ## Diagnostic log markers
 
 When investigating a CI failure, the install-step output in

.github/workflows/docker-build.yml

@@ -7,7 +7,27 @@ on:
     # in exchange for guaranteeing gramps-ci:<suffix> exists on the
     # first push to any newly-created maintenance branch.
     branches: [maintenance/gramps**]
+  pull_request:
+    # Build-only validation (no push — see the build step's `push:` and the
+    # login step's `if:`) when a PR touches the image definition, so a broken
+    # Dockerfile is caught before it merges instead of on the next push.
+    branches: [maintenance/gramps**]
+    paths:
+      - ".github/docker/**"
+      - ".github/workflows/docker-build.yml"
+  schedule:
+    # Weekly no-cache refresh so base-image (apt security) updates and new
+    # gramps patch releases enter the image even when nothing changes the
+    # buildx cache key. Fans out to every maintenance branch (see the
+    # weekly-rebuild job). NOTE: scheduled runs execute only from the repo's
+    # DEFAULT branch — inert until these workflows exist there.
+    - cron: "23 4 * * 1"
   workflow_dispatch:
+    inputs:
+      no-cache:
+        description: "Rebuild without the buildx layer cache (fresh base image + gramps)"
+        type: boolean
+        default: false
 
 env:
   REGISTRY: ghcr.io
@@ -20,11 +40,17 @@ permissions:
 jobs:
   build-ci:
     name: Build gramps-ci
+    # The schedule event is handled by weekly-rebuild (fan-out); this job runs
+    # for push / pull_request / workflow_dispatch.
+    if: github.event_name != 'schedule'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: Log in to GHCR
+        # Skip on pull_request: a fork PR's token is read-only and this build
+        # does not push, so the push credential is never exercised on a PR.
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
@@ -48,7 +74,7 @@ jobs:
         id: params
         shell: bash
         run: |
-          ref="${{ github.ref_name }}"
+          ref="${{ github.base_ref || github.ref_name }}"
           suffix="${ref#maintenance/}"
           case "$suffix" in
             gramps[0-9][0-9]) ;;
@@ -77,11 +103,41 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .github/docker/gramps-ci
-          push: true
+          # Push everywhere EXCEPT pull_request, where this is a build-only
+          # validation that must not touch GHCR.
+          push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |
             GRAMPS_SERIES=${{ steps.params.outputs.series }}
             GRAMPS_FALLBACK_SHA=${{ steps.params.outputs.fallback_sha }}
+          # `no-cache` (workflow_dispatch input; empty/false on other events)
+          # forces a from-scratch rebuild — used by the weekly refresh.
+          no-cache: ${{ inputs.no-cache == true }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
+
+  weekly-rebuild:
+    name: Weekly no-cache refresh (fan-out)
+    # The scheduled event fires only on the default branch; dispatch a no-cache
+    # rebuild for every maintenance branch that carries this workflow. Inert
+    # until these workflows reach the default branch — by design, not a bug.
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: write # gh workflow run
+    steps:
+      - name: Dispatch a no-cache rebuild per maintenance branch
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          git ls-remote --heads "https://github.com/${GITHUB_REPOSITORY}.git" \
+              'refs/heads/maintenance/gramps*' \
+            | awk -F'refs/heads/' '{print $2}' \
+            | grep -E '^maintenance/gramps[0-9][0-9]$' \
+            | while read -r branch; do
+                gh workflow run docker-build.yml --repo "$GITHUB_REPOSITORY" \
+                    --ref "$branch" -f no-cache=true \
+                  || echo "::warning::dispatch failed for $branch (workflow not on that branch yet?)"
+              done