Add CI/CD pipeline with container-based testing (Feature Request ID 9393 in Mantis)

[eduralph]

This is part of the answer to issue 9393, using the "X framebuffer" approach (Option 1 of the feature request).

Scope

This PR is strictly CI infrastructure. After review feedback from @kulath (2026-04-18) — "too many completely different changes in a single commit" — all per-addon code/lint/structure work that was originally bundled here has been split into one-PR-per-addon submissions; see the Companion PRs section at the bottom. This PR adds only the workflow files, the container image, the shared CI scripts, and a small shared test harness.

Thanks also to @GaryGriffin for the early testing feedback on bug 9393 and for asking the questions that led to the standalone per-job reproduction commands below.

What's in the PR

CI infrastructure

• .github/docker/gramps-ci/Dockerfile — Python 3.12 + Gramps 6.0 + PyGObject + GTK typelibs (incl. gir1.2-gexiv2-0.10 for EditExifMetadata / PhotoTaggingGramplet) + xvfb/xauth + ruff, intltool, gettext, git. GTK lives in the base image so addon modules that do from gi.repository import Gtk at module load are importable; xvfb/xauth are bundled for tests that actually render. Gramps is installed from PyPI for released series, or from a SHA-pinned gramps-project/gramps@maintenance/grampsNN snapshot for an unreleased branch (the series is parameterised via the GRAMPS_SERIES build arg).
• .github/workflows/docker-build.yml — rebuilds the image on .github/docker/** changes or via workflow_dispatch, deriving the image tag and Gramps series from the branch ref. Default-branch-only; gates on GHCR write access.
• .github/workflows/ci.yml — eight jobs:
  • Setup — derives the CI image tag and the make.py series suffix from the branch ref (maintenance/grampsNN), so the rest of the matrix is branch-neutral.
  • Lint — ruff --select=E9,F63,F7,F82 + trailing-whitespace check (uses grep -P so \t matches a real tab, not a literal t — see commit 205b21c for the regex bug fix).
  • Addon Structure — every addon has po/template.pot.
  • Compile Check — python3 -m py_compile on every .py.
  • Unit Tests (Linux) — <addon>/tests/test_*.py (skips test_windows_* / test_integration_*) via run_addon_tests.py (GI bootstrap + per-module timeout + honest skip accounting).
  • Unit Tests (Windows) — same matrix on the native Windows runner with a conda+pip env.
  • Integration Tests (Gramps) — tests/test_plugin_registration.py + <addon>/tests/test_integration_*.py, Linux-only, container --init so xvfb-run doesn't hang.
  • Build — make.py gramps60 build all.
• .github/environment.yml — hybrid conda+pip environment for Windows. Gramps isn't on conda-forge, so pygobject/gtk3 come from conda; only the stable base (gramps + orjson) comes from pip. Addon runtime deps (dbf, networkx, lxml, …) are no longer pinned here — ci.yml auto-derives and installs them at runtime from each .gpr.py's requires_mod (single source of truth; dbf dropped in commit 8d2654a).

Shared CI scripts

• .github/scripts/addon_system_deps.py — single source of truth for addon system dependencies. Maps each requires_gi typelib / requires_exe executable declared in a .gpr.py to its package on each CI platform (apt vs conda), and scans the tree so ci.yml derives the install list from one place instead of a hand-kept list. Records platform asymmetry (the GTK 3 libs — goocanvas, osm-gps-map, gexiv2 — exist on apt but not conda-forge). Pure stdlib.
• .github/scripts/run_addon_tests.py — per-addon unit/integration runner that replaces a bare python -m unittest: it (1) bootstraps the GI versions the Gramps GUI launcher pins (Pango/PangoCairo/Gtk) before any gramps.gui import, (2) runs each module in a subprocess with a wall-clock timeout so a hung test can't stall the job, and (3) FAILs a wholly-skipped module unless the addon's declared system deps are genuinely unavailable on the platform — so a silent skip can't read as a pass.
• .github/scripts/gi_bootstrap/sitecustomize.py — the same GI version pin as a sitecustomize shim, placed on PYTHONPATH for the discover-/subprocess-loading steps (e.g. plugin registration) so every spawned interpreter inherits the bootstrap.

Shared test harness

• tests/gramps_test_env.py — GrampsTestCase / GrampsDbTestCase base classes (stdlib unittest, mirroring upstream Gramps' own test style).
• tests/test_plugin_registration.py — registers every addon in a subprocess (crash-safe), verifies gramps_target_version=6.0 plus valid id/name/version, smoke-tests import/export entry functions.
• tests/__init__.py.

Docs

• CONTRIBUTING.md — a short note that PRs now run automated CI checks, and that a green check on an unreleased maintenance/grampsNN branch means the addon works against that branch tip (a SHA-pinned snapshot), not against a tagged release.
• .github/CI-MAINTAINER.md — operational runbook for a gramps-project/addons-source maintainer: one-time setup when this PR merges, and how to stand up a new maintenance branch. The pipeline is otherwise self-driving.

Gate policy

PR-blocking checks should only fire on issues the PR's own diff can cause. Every test here runs gramps or addon code, so the policy is:

• Blocking gates (job-level continue-on-error: false): Lint, Compile Check, Unit Tests (Linux), Unit Tests (Windows), Integration Tests, Build.
• Advisory gate (job-level continue-on-error: true): Addon Structure — the only advisory job.

Lint and both Unit-test jobs were advisory while their pre-existing backlog was being cleared by the companion PRs; that backlog is now cleared on maintenance/gramps60, so they were flipped to blocking (lint in d265612, both unit-test jobs in 0dd3f1b). The single remaining advisory is Addon Structure, which stays non-blocking until the four addons missing po/template.pot are fixed in a follow-up PR — flip it off in that PR.

Commits

SHA	Date	Summary
774a9ac	2026-04-19	Add CI/CD pipeline with container-based testing (issue 9393). Originally larger; force-pushed to this minimal scope after @kulath's review.
c6aa10e	2026-04-20	Auto-derive addon pip deps from requires_mod in .gpr.py.
8d2654a	2026-04-20	Remove dbf from image/env — installed via auto-derive now.
28febdc	2026-04-20	shell: bash on unit-test-linux + integration-test steps (fixes Dash Bad substitution).
715e71d	2026-04-20	OS-split addon tests by filename convention (test_linux_* / test_windows_* / test_integration_*).
dd0fd38	2026-05-11	Add gir1.2-gexiv2-0.10 typelib to image (companion to #878, #880).
205b21c	2026-05-11	Lint trailing-whitespace check — switch BRE [ \t] to PCRE. The previous BRE pattern matched any line ending in t/\/[/]/space (~3 000 false positives across ~430 files); PCRE (-P) recognises \t as a tab — real count 597 lines across 21 files.
f5907af	2026-05-15	Skip addons whose .gpr.py declares include_in_listing=False.
ff215ac	2026-05-16	Validate requires_mod names against find_spec (Pillow/PIL trap).
d265612	2026-05-19	Make the lint job blocking — ruff backlog cleared on maintenance/gramps60.
0dd3f1b	2026-05-19	Make unit-test-linux and unit-test-windows blocking — backlog cleared.
9a91d89	2026-05-18	Derive image tag and make.py argument from the branch ref.
abefdbe	2026-05-18	docker-build: derive image tag and Gramps series from the branch ref.
9927626	2026-05-18	Dockerfile: parameterise Gramps series via GRAMPS_SERIES build arg.
894e484	2026-05-18	CI image: hybrid PyPI / git-clone install for unreleased maintenance branches.
73d75ed	2026-05-18	docs: note the first-push race and unreleased-branch CI semantics.
3b2a947	2026-05-19	docs: add CI maintainer runbook (.github/CI-MAINTAINER.md).
ad2815c	2026-05-24	tests: detect addons that import a sibling without depends_on.
bc8df21	2026-05-24	tests: derive expected addon target version from the Gramps install.
7f8a839	2026-05-29	ci: install addon system deps, run under xvfb, pin GI, fail on silent skips.
1466491	2026-05-30	ci(windows): document the gramps-vs-branch series caveat.
06b95bc	2026-06-13	Strip the dependency detector and TMG test split out of the CI PR — moved to their own submissions so this PR stays strictly CI infrastructure (per @kulath's one-concern-per-PR feedback).

Local reproduction

This PR can't be exercised against gramps-project/addons-source directly (workflows live in the PR), but the per-job commands are reproducible standalone:

# Lint
ruff check --select=E9,F63,F7,F82 --no-fix --exclude='*.gpr.py' .
git --no-pager grep -P -n --full-name '[ \t]+$' -- '*.py' && echo FAIL || echo OK

# Addon Structure
for gpr in */*.gpr.py; do
  d="$(dirname "$gpr")"
  [ -f "$d/po/template.pot" ] || echo "MISSING: $d"
done

# Compile Check
find . -name '*.py' ! -path './.git/*' ! -path '*/__pycache__/*' \
  -exec python3 -m py_compile {} +

A complete end-to-end test is also available by forking to a personal repo and pushing a branch — the workflows fire because the workflow files come along with the fork. See the comment thread for the step-by-step walkthrough.

Companion PRs

Code/lint/structure work that was originally bundled here is now submitted as one-PR-per-addon. Tracker:

• Compile check (4) — Query: fix missing closing paren in QueryQuickview (line 347) #834 Query, HouseTimelineGramplet: escape backslash in ASCII-art string #835 HouseTimelineGramplet, Themes: use raw string for Windows registry path with backslash #836 Themes, lxml: use == not is when comparing os.name to a string literal #837 lxml.
• Lint backlog (24) — AnniversariesGramplet: import WindowActiveError #843, EditExifMetadata: use != to compare against empty-list literal #847-GrampsWebSync: add DbTxn and typing.Any imports #867 (excl. SourceReferences: import gramps.gen.errors as Errors #868), SurnameMappingGramplet: rename .grp.py and migrate Py2/Gramps-3 imports #869 SurnameMappingGramplet (rename + migration).
• Real bugs (5) — QuiltView: remove dead duplicate add_children_submenu method #870 QuiltView displayer, JSON: log repr(obj) on unrecognized object instead of undefined data #871 JSON data, LifeLineChartView: fix tuple-in-if outer condition for tooltip cache #872 LifeLineChartView tuple-in-if, libaccess: add missing value parameter to Person.gramps_id setter lambda #873 libaccess lambda (thanks to @GaryGriffin for catching that the first version of libaccess: add missing value parameter to Person.gramps_id setter lambda #873 was missing the actual code edit), lxml: drop self.uistate.window from module-level ErrorDialog calls #874 lxml module-level self.
• Plugin-registration migrations (3) — WordleGramplet: migrate Py2 / Gramps-3 era imports to Gramps 5+ #875 Wordle, SourceReferences: migrate Py2 / Gramps-3 era imports to Gramps 5+ #876 SourceReferences, RebuildTypes: migrate Py2 / Gramps-3 era imports to Gramps 5+ #877 RebuildTypes.
• Dependency declarations (3) — EditExifMetadata: declare Pillow and GExiv2 dependencies #878 EditExifMetadata (Pillow + GExiv2), MongoDB: declare pymongo in requires_mod #879 MongoDB (pymongo), PhotoTaggingGramplet: declare GExiv2 in requires_gi #880 PhotoTaggingGramplet (GExiv2).
• Trailing whitespace (6) — GeoTimeLines: remove trailing whitespace #881 GeoTimeLines, DNA: remove trailing whitespace #882 DNA, GraphView: remove trailing whitespace #883 GraphView, FamilyTreeDNA: remove trailing whitespace #884 FamilyTreeDNA, GrampyScript: remove trailing whitespace #885 GrampyScript, ToDoReport: remove trailing whitespace #886 ToDoReport.
• Gramps core companions (2) — Allow gui.clipboard to import without a default screen gramps#2299 (ClipboardGramplet headless-icon fallback), Define localAlphabeticIndex in the no-ICU fallback branch gramps#2302 (webreport/common.py no-ICU fallback) — both required to unblock plugin-registration smoke tests in this PR.

As of HEAD the lint and unit-test backlogs are cleared and those gates are blocking; once the remaining po/template.pot gaps land, Addon Structure can be promoted to blocking too.

🤖 Generated with Claude Code

[GaryGriffin]

Added Note to https://gramps-project.org/bugs/view.php?id=9393 requesting testing and feedback of this PR.

[eduralph]

Corrected to conform to the agents.md guidelines, including using unittest instead of pytest

[GaryGriffin]

Can you provide the commands to test the CI workflow. And a usage of the test harness.

[kulath]

How did the code work without the imports you have added

[kulath]

As per comment on another PR, the CLAUDE.md file should not be here as it just duplicates Agents.md in the main Gramps repository meaning any changes etc. will have to be made in two place and it will be hard to keep the files in step.

[kulath]

Thanks for fixing so many bugs and problems, but there are too many completely different changes in a single commit. Should they not be made in several commits(or even separate PRs).

[eduralph]

Yeah, I wanted more at one go, I can see that it might not be the right approach.

@kulath , there are many Lint issues and I chose to fix them them instead of dropping the Lint. I thought this might get some pushback. We can do it the other way around - I'll remove the Linting and we can make issues out of them as preperation for activating them.

[eduralph]

I've significantly reduced the scope of this PR based on @kulath's feedback about "too many completely different changes." It's now strictly CI infrastructure — 7 files, one commit.

What's in the PR

• .github/docker/gramps-ci/Dockerfile — container image for Linux CI jobs
• .github/environment.yml — conda environment for Windows CI
• .github/workflows/ci.yml — the CI workflow itself (lint, structure, compile, unit tests on Linux+Windows, integration, build)
• .github/workflows/docker-build.yml — publishes the CI image to GHCR
• tests/init.py
• tests/gramps_test_env.py — shared GrampsTestCase / GrampsDbTestCase base classes
• tests/test_plugin_registration.py — sanity checks that every registered plugin imports

Everything else from the earlier revision (lint fixes across ~29 addons, po/template.pot stubs for the four addons missing them, TMGimporter tests, the SurnameMappingGramplet.grp.py → .gpr.py rename, CLAUDE.md) has been removed and will be submitted as separate PRs.

Gate Policy

All seven jobs run on every push and PR. To avoid showering innocent contributors with red CI for pre-existing tree state, four jobs are marked continue-on-error: true so they surface issues without blocking merges:

lint — non-blocking (~79 pre-existing ruff E9/F63/F7/F82 errors)
addon-structure — non-blocking (4 addons missing po/template.pot)
unit-test-linux — non-blocking (some addon test modules fail to import today)
unit-test-windows — non-blocking (same)
compile-check — blocking (green today)
integration-test — blocking (green today)
build — blocking (green today)

In order to activate all gates, there will be some rework of existing addons needed

[eduralph]

@GaryGriffin — here are the commands for each CI job, lifted straight from ci.yml. Run from a checkout of addons-source with Gramps importable (either PYTHONPATH / GRAMPS_RESOURCES pointing at a Gramps checkout, or inside the CI container image).

Lint — syntax/import errors plus trailing whitespace

ruff check --select=E9,F63,F7,F82 --no-fix --exclude='.gpr.py' .
git --no-pager grep -n --full-name '[ \t]$' -- '.py' && echo FAIL || echo OK

Addon structure — every addon must have po/template.pot

for gpr in /.gpr.py; do
d="$(dirname "$gpr")"
[ -f "$d/po/template.pot" ] || echo "MISSING: $d"
done

Compile check — py_compile on every .py

find . -name '.py' ! -name '.gpr.py' ! -path './.git/' ! -path '/pycache/*'
-exec python3 -m py_compile {} +

Per-addon unit tests — matches both the Linux and Windows jobs

export PYTHONPATH=.
modules=""
for f in /tests/test_.py; do
[ -f "$f" ] || continue
case "$(basename "$f")" in test_integration*) continue ;; esac
case "$f" in Sqlite/tests/test_sqlite.py) continue ;; esac
mod="${f%.py}"; modules="$modules ${mod////.}"
done
python3 -m unittest -v $modules

Integration tests — plugin registration plus per-addon integration

export PYTHONPATH=.
python3 -m unittest discover -s tests -p 'test_*.py' -t . -v

per-addon integration uses the same loop as the unit block above
but matching test_integration.py instead*

[GaryGriffin]

here are the commands for each CI job, lifted straight from ci.yml.

Sorry, what I meant was, is there a way to invoke the CI process (not the commands that are invoked by the CI process) manually to test the github actions.

I did try the invoked commands:

Lint: I dont have ruff on my Mac. How would I invoke the CI lint process within github as an action.

Addon Structure: if I manually invoke the commands on my Mac that is in the comment, it fails (due to escaping special chars needed for comments). I need to use:

for gpr in */*.gpr.py; do
d="$(dirname "$gpr")"
[ -f "$d/po/template.pot" ] || echo "MISSING: $d"
done

Results: 4 issues, as you stated. I do not know if it is a requirement that the template.pot exists. If there are no translated strings, then there shouldn't need to be one, I think. Maybe I am wrong.

Compile Check: same issue with escaping special chars. I think the gpr.py should actually be included. I need to use:

find . -name *.py -exec python3 -m py_compile {} \;

Results: 4 issues - Themes, Query, HouseTimelineGramplet, and lxml

Integration Tests: failed with error ImportError: Start directory is not importable: 'tests' .

[eduralph]

Can you tell me what you are trying to do or understand? I'm not sure if I'm giving you the right answers.

The tests run in containers stored on ghcr.io containing all the necessary tools. It's optimized for steady-state but is kind of a pain for this specific PR, because you can't really test it in this environment. The upside is that the image is stable across hundreds of normal PRs. It only churns when someone explicitly wants the CI environment to change.

• The Dockerfile changes rarely. Maybe once per Gramps minor, or when a system dependency is added. Most weeks, nobody touches .github/docker/**.
• The path filter ensures docker-build doesn't fire on every push — only when the Dockerfile actually changes. So in steady state, ci.yml pulls a stable, cached image and runs fast.
• The "default branch only" scope ensures one canonical image per supported branch (:gramps60). PR-built images would proliferate (:gramps60-pr123, :gramps60-pr124...) and clutter GHCR with throwaway tags that need lifecycle management.
• GHCR write access is gated to default-branch context. Fork PRs have read-only GITHUB_TOKEN, so a pull_request: trigger on docker-build would silently no-op for external contributors anyway. Even internal PRs publishing to GHCR would mean unmerged code can write to the registry — a small but real trust-boundary violation.

You will have to make the images publically available for the PRs to work, but I don't think that's an issue. There will be some maintainance work needed to be done once you flip over to branch61 as default, I'd see what can be done to make it a bit easier then, assuming you like the current process.

In order for you to verify how it works, take a poke at my forked repo where I've merged the PR. This is how you can do it

1. Fork eduralph/addons-source to your account using GitHub's "Fork" button: https://github.com/eduralph/addons-source/fork.
2. Create a branch off maintenance/gramps60 on your new fork — e.g., test/ci-tryout. The CI workflow files come along automatically.
3. Make any change you want to exercise the pipeline, or none at all if you just want to see a clean run. Some ideas:
   • Add a deliberate import nonexistent_module to any .py file → trips the Lint job.
   • Add a stray syntax error → trips the Compile Check job..
   • Modify a real addon you care about → exercises the Build job and unit/integration tests.
4. Commit, push, and open a PR from your branch targeting eduralph/addons-source:maintenance/gramps60. (Not gramps-project/addons-source — point the PR base at my fork.)
5. Wait for approve the first workflow run. Because you'll be a first-time contributor to my fork, GitHub will hold the run for manual approval — click the "Approve and run workflows" button on the PR. Subsequent runs go automatically.
6. Watch the Checks tab on your PR. You'll see 7 jobs fire:
   • 5 Linux jobs (Lint, Addon Structure, Compile Check, Unit Tests Linux, Integration Tests, Build) running in the public container.
   • 1 Windows job (Unit Tests Windows) on a GitHub-hosted Windows runner with a conda environment.
   • The advisory ones (Lint, Addon Structure, Unit Tests Linux/Windows) will report red without blocking your PR; the blocking ones (Compile Check, Integration Tests, Build) gate the merge.

[GaryGriffin]

Can you tell me what you are trying to do or understand? I'm not sure if I'm giving you the right answers.

I should have been more explicit. I am trying to test the implementation before merging/publishing this PR. Understanding the resources needed and the frequency of activity is part of that. And making sure that it functions completely and as expected.

I was hoping for something like a github command to activate the action so I can see it work. Given your complete description (much appreciated), I think I am going to have to yield to @Nick-Hall to review/merge/publish this one since it impacts the repo actions in ways far above my knowledge of github. For instance, I dont know if these are the right blocking/non-blocking decisions. Or if the scope should just be the Addon impacted by the PR rather than all Addons.

[eduralph]

@GaryGriffin - I thought of adding a manual button for everything, but that only works if it's merged with the default branch, lol

[eduralph]

I just reworked the CI approach a bit to be able to differentiate between Base, Linux & Windows test specifically. Also added automated dependency loading for future unit tests. The Unit Tests currently fail because of an issue in Websearch, but that needs to be adressed seperately.

[dsblank]

Note that if/when the mini-installer from gramps-project/gramps#2308 is merged, that it uses slightly different names (pip names rather than import names).

[Nick-Hall]

I plan to review #2308 next and it will probably be merged.

[eduralph]

@dsblank - I've added some stuff on that account to PR 820 now
@Nick-Hall - I'll update the rest of the dependency once PR 2308 lands

[dsblank]

How far away are we from having even a basic CI test framework ready?

[dsblank]

Noting that gramps-project/gramps#2308 has been merged.

[eduralph]

@dsblank — PR #2308 is now accounted for (commits 427f8c3 + ad98e1d):

• Name mapping single-sourced. addon_python_deps.py now reads _IMPORT_TO_PYPI from the installed gramps' gen/utils/pypi.py at lookup time, so 6.1+ lanes install exactly what Gramps' own installer would — including entries added upstream later. The local table remains only as a fallback mirror for lanes where gramps predates 6.1 (the gramps60 image, the conda-forge Windows lane, bare runners), with a sync-guard test (tests/test_addon_python_deps.py::GrampsTableSync) that fails on any drift wherever gramps ≥ 6.1 is importable.
• The --check-resolves gate delegates to Requirements().check_mod, so it matches whichever series the lane ships: find_spec-only on 6.0, find_spec plus a real import on 6.1+.
• Fixed along the way: the pip-installed-ness probe used the raw import name (pip show PIL fails even with Pillow installed), which would have silently skipped exactly the declarations the mapping exists for; it now probes by the mapped distribution name while still judging the raw import name.

One small upstream observation from wiring this up: resolve_pypi_name()'s warning advises addon authors to update requires_mod to the PyPI name (e.g. "Pillow"), but check_mod verifies the import name — find_spec("Pillow") fails, so an addon following that advice would report its dependency as unsatisfied. The import name plus the _IMPORT_TO_PYPI translation seems to be the consistent contract; the warning text might be worth revisiting in gramps.

[eduralph]

Ran an adversarial review of this PR (four independent passes: workflow logic, helper scripts, test adequacy via mutation testing, and CI security) and pushed fixes for everything that survived verification. Summary of what changed:

Blocking (CI couldn't pass its own first run):

• The lint gate was red on pre-existing base files — 27 trailing-whitespace lines and a real UnboundLocalError in AssociationsTool (for _ in range(...) shadowing the gettext _). Split into a separate PR against maintenance/gramps60 (Fix trailing whitespace and a shadowed gettext _ in AssociationsTool #996) since it's not pipeline code; this PR's lint lane goes green once that merges and is merged back.
• Fixed a false-red I'd introduced in tests/test_addon_python_deps.py: the {"gramps": None} overlay didn't force ImportError when a gramps.* submodule was already cached (which the integration lane does via test_plugin_registration), so test_stdlib_fallback took the delegated path and failed. The overlay now None-outs every cached gramps.* key.

Test blind spots (mutation-tested):

• test_no_requires_mod_heredoc_remains was a tautology (its regex could never match the old heredoc's literal \s* text) — now matches the heredoc's real fragments.
• The Dockerfile toolchain assertions were line-based and missed a multi-line purge, apt-get -y purge ordering, and dropping python3-dev — now scans logical lines and asserts all three tools.
• CheckResolvesGate stubs were constant lambdas that let a "judge by distribution name" mutant survive — now assert the gate judges the raw import name.

Security:

• Added permissions: contents: read to ci.yml (it runs addon-influenced pip/import code and had no permissions block).
• The --unmapped drift gate ran only on the Linux lane; unit-test-windows pip-installed derived requires_mod unguarded. Added the gate there too.
• Pinned ruff in the image so the lint verdict can't drift across rebuilds.

Correctness / fail-open:

• check_resolves now fails (not skips) when a wheel-only requires_mod never installed — a pure wheel that doesn't install is a real regression, not an environment gap. Source-built deps stay advisory.
• run_addon_tests.py: the per-module timeout was defeated by a grandchild holding the stdout pipe (fixed with process-group kill + bounded wait); a module-level ImportError was misclassified (it becomes a _FailedTest, not a raise) while a SyntaxError on an unsatisfiable platform was excused — now the load-failure taxonomy is honest (dep-shaped → skippable, code bug → always fails); a zero-test module (read as green by unittest) now fails; a non-integer timeout env no longer crashes the runner.
• Both dep scanners now skip a tuple-shaped requires_mod entry with a note instead of crashing with a TypeError.
• is_active is now ast-based/per-register/comment-proof (matching make.py's per-registration rule), replacing the file-granular grep — verified behaviour-identical across all 146 current addon dirs, with the whole-tree oracle embedded as a test.

Lifecycle / docs:

• docker-build.yml: PR builds validate the image without pushing, a no-cache dispatch input, and a weekly refresh; documented the one-push image lag.
• Corrected the environment.yml/ci.yml comments that claimed the Windows lane's gramps comes from conda-forge (it's PyPI) and "self-heals" to 6.1 (the pin needs a manual per-branch bump); lowercased the GHCR image ref so mixed-case fork owners can pull.

13 commits total. All five CI-owned test modules pass locally (49 tests, ruff clean). Next I'm validating the full container pipeline on both the 6.0 and 6.1 lanes on my fork before considering this ready.

[dsblank]

One small upstream observation from wiring this up: resolve_pypi_name()'s warning advises addon authors to update requires_mod to the PyPI name (e.g. "Pillow"), but check_mod verifies the import name — find_spec("Pillow") fails, so an addon following that advice would report its dependency as unsatisfied. The import name plus the _IMPORT_TO_PYPI translation seems to be the consistent contract; the warning text might be worth revisiting in gramps.

What should we do here? Is just changing the warning text enough? Or does something need to change for a proper check?

Also noting relationship to: gramps-project/gramps#2250