CI image: hybrid PyPI / git-clone install for unreleased maintenance branches

Mirrors the same-named commit on ci/branch-neutral
(951166afe). The bootstrap commit on this
branch hit "No matching distribution found for gramps==6.1.*" because
no 6.1 release exists on PyPI yet; this commit adds the SHA-pinned
git-clone fallback to the Dockerfile and the matching SHA capture in
docker-build.yml so the gramps61 image can actually build.

See the parent commit (951166afe on ci/branch-neutral) for the design
write-up, local verification log (gramps60 PyPI path + gramps61
fallback path + bash unit tests of the failure-mode triage), and the
::notice:: / ::warning:: log convention.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: eduralph

.github/docker/gramps-ci/Dockerfile

@@ -16,9 +16,27 @@
 # `--init` (or use a container runtime that injects tini) because xvfb-run
 # hangs if it inherits PID 1.
 #
-# Local build:
+# Gramps install path. PyPI is tried first; when no gramps==${SERIES}.*
+# release exists (e.g. while 6.1 is still in development) the build
+# falls back to a SHA-pinned git clone of
+# gramps-project/gramps@maintenance/gramps${SERIES_NODOT}. Other pip
+# failures (network, etc.) are NOT silently retried so a transient
+# PyPI outage cannot flip a normally-released branch to "test against
+# moving tip" mode. docker-build.yml captures the upstream SHA via
+# git ls-remote and passes it in as GRAMPS_FALLBACK_SHA; the SHA
+# becomes part of the buildx cache key so a moved upstream tip
+# actually re-runs the install layer.
+#
+# Local build (released series):
 #   docker build --build-arg GRAMPS_SERIES=6.0 .github/docker/gramps-ci
 #
+# Local build (unreleased series, e.g. 6.1):
+#   sha=$(git ls-remote https://github.com/gramps-project/gramps.git \
+#         refs/heads/maintenance/gramps61 | awk '{print $1}')
+#   docker build --build-arg GRAMPS_SERIES=6.1 \
+#                --build-arg GRAMPS_FALLBACK_SHA=$sha \
+#                .github/docker/gramps-ci
+#
 ARG PYTHON_VERSION=3.12
 FROM python:${PYTHON_VERSION}-slim
 
@@ -27,6 +45,11 @@ FROM python:${PYTHON_VERSION}-slim
 # for the wrong Gramps series. docker-build.yml derives this from the
 # branch ref.
 ARG GRAMPS_SERIES
+# Commit SHA on gramps-project/gramps@maintenance/grampsNN. Only used
+# when no gramps==${GRAMPS_SERIES}.* release exists on PyPI. Ignored
+# otherwise. Empty default is intentional — on released branches the
+# fallback never fires.
+ARG GRAMPS_FALLBACK_SHA=""
 RUN [ -n "$GRAMPS_SERIES" ] || { echo "GRAMPS_SERIES is required (e.g. 6.0)"; exit 1; }
 
 LABEL org.opencontainers.image.source="https://github.com/gramps-project/addons-source"
@@ -50,13 +73,34 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         xauth \
     && rm -rf /var/lib/apt/lists/*
 
-RUN pip install --no-cache-dir \
-        PyGObject \
-        pycairo \
-        "gramps==${GRAMPS_SERIES}.*" \
-        orjson \
-        ruff \
-        dbf
+RUN pip install --no-cache-dir PyGObject pycairo orjson ruff dbf
+
+# Install gramps: PyPI first, SHA-pinned git clone as fallback.
+RUN /bin/bash -eo pipefail <<'BASH'
+suffix_nodot="${GRAMPS_SERIES//./}"
+if pip install --no-cache-dir "gramps==${GRAMPS_SERIES}.*" 2>/tmp/pip.err; then
+    echo "::notice::installed gramps==${GRAMPS_SERIES}.* from PyPI"
+elif grep -q "No matching distribution found for gramps==" /tmp/pip.err; then
+    if [ -z "${GRAMPS_FALLBACK_SHA}" ]; then
+        echo "::error::no gramps==${GRAMPS_SERIES}.* on PyPI and GRAMPS_FALLBACK_SHA is unset"
+        exit 1
+    fi
+    echo "::warning::no gramps==${GRAMPS_SERIES}.* on PyPI; installing from gramps-project/gramps@maintenance/gramps${suffix_nodot} at ${GRAMPS_FALLBACK_SHA}"
+    mkdir -p /tmp/gramps
+    cd /tmp/gramps
+    git init -q
+    git remote add origin https://github.com/gramps-project/gramps.git
+    git fetch --depth 1 origin "${GRAMPS_FALLBACK_SHA}"
+    git checkout FETCH_HEAD
+    pip install --no-cache-dir .
+    cd /
+    rm -rf /tmp/gramps
+else
+    echo "::error::pip install gramps failed (non-version reason); aborting rather than silently switching to git tip"
+    cat /tmp/pip.err
+    exit 1
+fi
+BASH
 
 RUN apt-get purge -y gcc python3-dev pkg-config && apt-get autoremove -y
 

.github/workflows/docker-build.yml

@@ -35,9 +35,16 @@ jobs:
         uses: docker/setup-buildx-action@v3
 
       - name: Compute branch parameters
-        # Derive the image-tag suffix and Gramps minor series from the
-        # branch ref. Same validation as ci.yml's setup job: anything
-        # outside maintenance/grampsNN fails fast.
+        # Derive the image-tag suffix, Gramps minor series, and upstream
+        # fallback SHA from the branch ref. Same validation as ci.yml's
+        # setup job: anything outside maintenance/grampsNN fails fast.
+        # The fallback SHA is the current tip of gramps-project/gramps
+        # at the matching maintenance branch; the Dockerfile only uses
+        # it when no gramps==${series}.* release exists on PyPI. The
+        # SHA is part of the buildx cache key so a moved upstream tip
+        # actually re-runs the install layer (otherwise gramps61 CI
+        # would stay on the same stale gramps revision build after
+        # build).
         id: params
         shell: bash
         run: |
@@ -49,8 +56,13 @@ jobs:
           esac
           # gramps60 → 6.0, gramps61 → 6.1, gramps62 → 6.2, …
           series="${suffix:6:1}.${suffix:7}"
-          echo "suffix=$suffix" >> "$GITHUB_OUTPUT"
-          echo "series=$series" >> "$GITHUB_OUTPUT"
+          fallback_sha=$(git ls-remote https://github.com/gramps-project/gramps.git "refs/heads/maintenance/${suffix}" | awk '{print $1}')
+          if [ -z "$fallback_sha" ]; then
+            echo "::warning::upstream gramps-project/gramps has no maintenance/${suffix} branch; fallback path will fail if PyPI lacks gramps==${series}.*"
+          fi
+          echo "suffix=$suffix"            >> "$GITHUB_OUTPUT"
+          echo "series=$series"            >> "$GITHUB_OUTPUT"
+          echo "fallback_sha=$fallback_sha" >> "$GITHUB_OUTPUT"
 
       - name: Docker metadata
         id: meta
@@ -70,5 +82,6 @@ jobs:
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |
             GRAMPS_SERIES=${{ steps.params.outputs.series }}
+            GRAMPS_FALLBACK_SHA=${{ steps.params.outputs.fallback_sha }}
           cache-from: type=gha
           cache-to: type=gha,mode=max