CI profiles¶
Rhiza's GitHub CI supports three presets for choosing how often compatibility checks and optional workflows run. This can help private projects manage Actions usage while retaining supported Python versions, coverage thresholds and quality checks.
The presets govern rhiza_ci.yml and the pull-request runs of the optional
CodeQL and marimo workflows. Every other workflow keeps its own triggers and
switches; the per-workflow table lists them all.
Select a profile¶
Add this consumer-owned setting to pyproject.toml:
Supported values are lean, standard and comprehensive. Omitting the setting
selects comprehensive, preserving the existing set of CI checks. Unknown profiles
or unknown keys in this table fail CI planning — and the profile gate of each
optional workflow — rather than silently reducing checks.
This setting is separate from the bundle profiles in .rhiza/template.yml:
those choose which files Rhiza supplies; this preset controls when the GitHub
workflows run. Consumers keep the template-owned workflow stubs and receive
workflow updates normally.
Validation scope¶
| Profile | PRs and default-branch pushes | Scheduled compatibility validation |
|---|---|---|
| Lean | Tests and coverage on the primary Python version, on Ubuntu; consolidated quality checks | Tests across supported Python versions and configured operating systems; lowest-direct dependencies |
| Standard | Tests and typing across supported Python versions; separate quality jobs | Full matrix and lowest-direct dependencies |
| Comprehensive (default) | Full test and typing matrices, lowest-direct dependencies, separate quality jobs | Full matrix and lowest-direct dependencies |
Every profile runs formatting and lint hooks, dependency hygiene, type checking,
repository checks, docstring coverage, security scanning and license compliance.
Lean invokes the same pinned task gates in one job. A failure stops that job and
fails the aggregate check. Standard and Comprehensive retain the existing separate
jobs and their artifacts. Lean does not generate the separate LICENSES.md artifact.
The primary Python version comes from .python-version, with patch versions
normalised to major/minor for the matrix. If the file is absent, CI uses the first
version returned by the package classifier metadata. The primary version must
appear in the supported Python classifiers. The full matrix still comes from
those classifiers and the existing Rhiza OS configuration. Lean uses Ubuntu for
routine checks and restores the configured OS matrix on scheduled or full manual
runs. The configured primary Python version supplies the coverage upload and
clean-working-tree check on Ubuntu.
The CI compatibility schedule runs on Monday at 07:17 UTC. The existing weekly
workflow separately checks latest compatible dependencies at 08:00 UTC. Consumers
need the github bundle's weekly workflow as well as github-tests to receive
both; selecting Lean alone does not install missing bundles. Scheduled runs use
the default branch and report results separately from PR checks.
What runs where¶
A workflow only runs if its bundle is synced. The table shows, for each workflow the GitHub bundles ship, what each profile runs on a pull request and what runs regardless of profile.
| Workflow (bundle) | PR: Lean | PR: Standard | PR: Comprehensive | Default-branch push, schedule, manual | Other switches |
|---|---|---|---|---|---|
rhiza_ci.yml (github-tests) |
Primary Python on Ubuntu, one quality job |
Full matrix, separate quality jobs | Full matrix, lowest-direct dependencies, separate quality jobs | Push follows the profile; Monday 07:17 UTC schedule and full-validation dispatch run everything | RHIZA_SETUP_ENABLED |
rhiza_codeql.yml (github-tests) |
Skipped | Skipped | Runs | Push to main/master, Monday 01:27 UTC schedule, manual dispatch |
CODEQL_ENABLED (false disables; true forces it on a private repo; unset runs on public repos only) |
rhiza_benchmark.yml (github-tests) |
Never runs on PRs | Never runs on PRs | Never runs on PRs | Push to main, manual dispatch |
RHIZA_SETUP_ENABLED |
rhiza_marimo.yml (github-marimo) |
Skipped | Skipped | Runs | Push to main/master, manual dispatch |
Notebook folder (marimo-folder setting); an empty folder runs nothing |
rhiza_book.yml (github-book) |
Never runs on PRs | Never runs on PRs | Never runs on PRs | Builds on every branch push; deploys to Pages only from the default branch and never from a fork | deploy-pages input; RHIZA_SETUP_ENABLED |
rhiza_docker.yml (github-docker) |
Runs | Runs | Runs | Push to main/master |
Bundle selection |
rhiza_devcontainer.yml (github-devcontainer) |
Runs on .devcontainer/ changes |
Same | Same | Push touching .devcontainer/ |
DEVCONTAINER_REGISTRY, DEVCONTAINER_IMAGE_NAME |
rhiza_paper.yml (github-paper) |
Runs on docs/paper/ changes |
Same | Same | Push to main/master touching docs/paper/ |
Bundle selection |
rhiza_quality_review.yml (github-quality-review) |
Runs | Runs | Runs | — | CLAUDE_QUALITY_REVIEW_ENABLED |
rhiza_weekly.yml (github) |
Never runs on PRs | Never runs on PRs | Never runs on PRs | Monday 08:00 UTC schedule, manual dispatch | RHIZA_SETUP_ENABLED |
rhiza_scorecard.yml (github) |
Never runs on PRs | Never runs on PRs | Never runs on PRs | Push to main/master, Tuesday schedule, ruleset changes, manual dispatch |
SCORECARD_ENABLED |
rhiza_release.yml (github) |
Never runs on PRs | Never runs on PRs | Never runs on PRs | Version tags only | PUBLISH_CONDA, PUBLISH_DEVCONTAINER, RELEASE_PUBLISHER, PYPI_REPOSITORY_URL |
"Skipped" means the workflow still starts: a small CI profile job reads
[tool.rhiza.ci].profile, because GitHub's on: triggers cannot read
pyproject.toml, and the expensive jobs that need it are skipped. A skipped job
reports as skipped, not failed, and none of these jobs is a required status
check. The profile job itself fails on an invalid profile, exactly as the CI
planner does. Under CodeQL it carries the CODEQL_ENABLED condition too, so a
repository with CodeQL switched off starts no runner at all.
Two consequences of skipping CodeQL on PRs are worth knowing before choosing Lean or Standard. Code-scanning alerts for a change appear only after it reaches the default branch, not on the pull request. And a repository that adds GitHub's code scanning merge-protection rule to its own ruleset would wait on results a skipped PR never produces; the shipped ruleset does not include that rule.
Mutation testing is not offered in any profile; the workflow and the task were removed (see the CI enforcement page).
Triggers and documentation changes¶
CI runs for pull requests targeting any branch and for pushes to the repository's actual default branch. Other branch pushes skip CI, avoiding a second full run for the same change when a PR is open. A branch without a PR receives no automatic application validation; use manual dispatch when needed.
For PRs and default-branch pushes, CI examines the complete Git diff. Changes
limited to top-level Markdown files or recognised documentation files under
docs/ skip the application test matrix, separate typing matrix and dependency
floor tests. The quality checks still run, including README and repository
validation; Lean's consolidated job also retains primary-version typing. This does
not build or publish a documentation site.
The recognised documentation extensions are .md, .rst, .txt, .png, .jpg,
.jpeg, .gif, .svg and .webp. Code, workflow, dependency and documentation
configuration changes trigger application validation. Missing history, an empty
diff or an unknown file type also retains application validation. Scheduled and
full manual runs always run application tests regardless of the diff.
Full validation on demand¶
Use Actions → (RHIZA) CI → Run workflow and enable full-validation to run the complete test matrix and lowest-direct dependency tests for any profile. Leaving it disabled uses the chosen profile. This expands compatibility testing; it does not start the optional workflows. Run (RHIZA) CODEQL, (RHIZA) MARIMO or (RHIZA) BENCHMARK the same way to exercise one on demand: a manual run is not a pull request, so the profile never skips it.
Branch protection and migration¶
CI gate is the aggregate check across profiles. In a consumer using the shipped
ci caller job, GitHub displays it as ci / CI gate. The github bundle's
rulesets/main-branch-protection.json requires exactly that context and nothing
else.
Earlier releases required six contexts: ci / CI gate plus ci / Pre-commit hooks,
ci / Check dependencies with deptry, ci / docs-coverage, ci / Security scanning
and ci / License compliance scan. Lean runs those five gates inside one quality
job, so their contexts never report and a Lean PR waits on them forever. The
aggregate loses nothing by standing alone: it needs every CI job, and it fails when
any job the planner selected failed, was cancelled or was unexpectedly skipped.
The synced file is not the live setting. GitHub does not read rulesets from the repository, so syncing the new file changes no protection. A repository that applied the old file keeps requiring all six contexts until it re-applies the new one, for example:
gh api repos/<owner>/<repo>/rulesets --jq '.[] | "\(.id)\t\(.name)"'
gh api --method PUT repos/<owner>/<repo>/rulesets/<RULESET_ID> \
--input .github/rulesets/main-branch-protection.json
Under Standard or Comprehensive the old contexts still report, so the stale ruleset is redundant but harmless; under Lean it blocks every PR. Re-apply before switching to Lean.
The gate requires every job selected by the planner to finish successfully. Intentional profile or documentation skips are allowed; failed, cancelled or unexpectedly skipped required jobs fail the gate. A failed planner also fails the gate, so an invalid configuration cannot produce a successful empty test run.
Scope and usage implications¶
Fewer matrix jobs, shared runner setup and skipped optional workflows on PRs should reduce routine Actions usage for Lean and Standard projects, but actual usage depends on suite duration, caching, operating systems and the other installed workflows. The presets make no fixed cost or savings guarantee. A weekly full matrix may still consume substantial minutes, and the book still builds on every branch push.
The profiles do not change documentation publishing, benchmarks, release
automation or GitLab pipelines. Those keep the bundle selection and repository
variables listed in the table above; leaving a bundle out of .rhiza/template.yml
remains the way to stop a workflow running at all.