CI/CD Pipelines Matrix

Overview

Every product site in the Flude ecosystem self-deploys from its own repository directly to Cloudflare Pages. There is no cross-repository trigger mechanism, no shared umbrella build, and no repository_dispatch orchestration — each repository's own push/pull_request events are sufficient to build and deploy that repository's site. Pipeline (the umbrella repo) does not build or deploy anything itself.

This replaces an earlier architecture (removed 2026-07-22) where a Pipeline-owned umbrella workflow received repository_dispatch events from child repos and orchestrated a combined build. That mechanism added a cross-repo dependency without adding real value — each repo's own CI already has everything it needs to build and deploy itself.

Pipelines Matrix

Repository	Workflow	Deploys to	Triggers
engine	publish-api-ref.yml	api-ref.flude.guide (flude-api-ref)	push/pull_request to main, workflow_dispatch
design-docs	deploy.yml	design.flude.guide (flude-design-docs)	push/pull_request to main, workflow_dispatch
user-docs	deploy.yml	user.flude.guide (flude-user-docs) + flude.guide (flude-landing)	push/pull_request to main, workflow_dispatch
ude_promotion	deploy.yml	blog.flude.guide (flude-blog)	push/pull_request to main, workflow_dispatch
Pipeline	bump-submodule.yml	(none — opens a PR)	schedule (6h), workflow_dispatch
Pipeline	integration_tests.yml	(none — regression gate)	push/pull_request to main, workflow_dispatch
Pipeline	regression.yml	(none — trend-watch)	schedule (weekly), workflow_dispatch

Pipeline's three workflows exist only to keep the engine/design-docs/user-docs submodule pins current and to run regression checks that need all three checked out together — they are not part of any product's deploy path.

Alerting

Every workflow above alerts on failure via a local copy of a shared Telegram/GitHub- issue notifier composite action (.github/actions/notify), duplicated into each of the five repositories rather than fetched from Pipeline at run time — this removes a cross-repo dependency that a shared, centrally-fetched action would otherwise introduce.

Local Pre-Push Guard

Pipeline's .githooks/pre-push runs the same regression suite as the python-regression job in integration_tests.yml — tests/integration/regression/run_regression_tests.py — locally, before a push ever reaches the remote, so failures are caught before CI even starts.

It is not enabled by default (Git doesn't run hooks outside .git/hooks/ unless told to). Enable it once per local clone:

git config core.hooksPath .githooks

It sets TRACKED_ONLY=1 before running, which scopes the check to exactly the 4 mock_api_* fixtures that are actually git-tracked — the same 4 that CI's python-regression job validates on a fresh checkout. The other 8 fixtures (facetmodeler_api_*, bimnv_api_*) exist only as whatever a developer happened to generate locally and are gitignored; running the hook without TRACKED_ONLY (by invoking run_regression_tests.py directly) checks those too, but that's a deliberate local-only check, not what CI enforces.

To skip it for one push (e.g. a WIP branch): git push --no-verify. To disable it entirely: git config --unset core.hooksPath.

Coverage Gates: Two Different 98% Numbers

Two workflows each enforce a 98% threshold, but they measure completely different things — easy to conflate by name alone:

Workflow	Gate	Measures
engine/.github/workflows/ci.yml	pytest --cov=ude --cov-fail-under=98	Test coverage — the fraction of engine's own Python statements exercised by its test suite.
engine/.github/workflows/publish-api-ref.yml	"Documentation Coverage Audit (98% gate)" step (python -m ude.cli audit --mode reject-undocumented --threshold 98)	Documentation coverage — the fraction of engine's own public API entities that carry a docstring, as compiled by Flude itself.

publish-api-ref.yml runs its documentation-coverage gate in two places: a pr-coverage-check job (every pull request — coverage check only, no build) and, separately, as the first step of the parse-render-deploy job (any non-pull-request trigger — push to main or manual workflow_dispatch) — coverage is verified there too, before Doxygen/Hugo ever run and before the compiled site is deployed to Cloudflare Pages.

Related Docs

(Paths below are repository-root-relative.)

• .github/AGENTS.md — per-workflow trigger and secret catalog
• user-docs/docs/admin-deployment.md — deployment mechanics for a single repo's workflow
• user-docs/docs/deployment/secrets.md — secrets these workflows depend on