Skip to content

CI and validation

TopMark uses a deliberately explicit CI and validation structure. GitHub workflows provide orchestration, nox sessions define stable reusable validation contracts, pytest markers describe validation intent, and Makefile targets provide local developer shortcuts.

Note

The canonical vocabulary used throughout the documentation is defined in Terminology and Canonical Vocabulary.

The current design favors clarity, deterministic behavior, and release safety over aggressive workflow abstraction. Some repetition between workflows is intentional, especially where privileged release behavior or artifact trust-boundary behavior is involved.

Validation architecture

Repository-source validation starts in the main CI workflow and is delegated to nox sessions where practical. The test suite is further organized with pytest markers so contributors can understand the intent and expected scope of each test group.

  • CI workflow - validates repository source trees, documentation, tests, typing, linting, API snapshots, and release artifacts produced from trusted CI runs.
  • Setup Python + nox action - documents the shared Python, uv, cache, and nox bootstrap layer used by CI jobs.
  • Test validation - explains pytest markers, validation categories, local test commands, CI inclusion rules, and how nox and Makefile targets map onto the test suite.
  • Published artifact validation - validates installation and runtime behavior from packages already published to PyPI or TestPyPI in clean runner environments.

Release infrastructure

Release publication is intentionally separated from normal repository-source validation. The release workflow is privileged and consumes artifacts produced by the CI workflow instead of rebuilding them in the publishing context.

  • Release workflow - publishes previously built release artifacts after release-tag, artifact, and repository validation checks.
  • Published artifact validation - verifies the package as an end user would install it after publication.

Dependency automation

Dependency automation is documented separately because it has different triggers, trust boundaries, and maintenance expectations than repository-source validation or release publication.

Contributor mental model

Use this family of pages as follows:

Question Start here
What runs on pull requests and pushes? CI workflow
How are Python, uv, and nox bootstrapped in CI jobs? Setup Python + nox action
Which tests are included, skipped, slow, or integration-focused? Test validation
How are release artifacts produced and published? Release workflow
How do we validate packages after publication? Published artifact validation
How are dependency updates handled? Dependabot
How do we audit GitHub Action pin consistency? GitHub Action pin audit

CI and release validation model

TopMark intentionally separates:

  1. repository source-tree validation;
  2. dependency and GitHub Action maintenance;
  3. release artifact construction in CI;
  4. privileged artifact publication;
  5. post-publication package validation from PyPI or TestPyPI.

This layered model keeps source validation, artifact production, package publication, and published-package validation in distinct trust boundaries for the stable 1.x release line.