Quality and Security Harness

voiage treats repository automation as a release surface. The local harness and GitHub workflows therefore validate both Python behavior and the controls that protect changes, dependencies, and published artifacts.

Local gates

Run affected checks during iteration and the complete gate once for the final candidate:

tox run-parallel -p 2

The harness is included in tox; a second standalone harness run is unnecessary. Record the tested tree, environment and result. Reuse successful local evidence when these inputs remain unchanged. A new runtime, dependency, shared-fixture or test-infrastructure change requires broader validation. Hosted required checks remain bound to the current PR revision. Batch edits before pushing, rebase locally with signed commits, and inspect the actual failed gate before changing a branch; repeated pushes restart hosted validation.

The harness tox environment checks that workflows declare explicit permissions, external actions are pinned to immutable commits, required security workflows exist, and repository governance files are present. The full tox environment additionally runs linting, type checking, docs, contract validation, the supported Python matrix, and the coverage threshold.

The installed-provider consumer test uses a private download cache by default and ignores an inherited UV_CACHE_DIR. To reuse an existing writable cache deliberately, locate it with uv cache dir, then set VOIAGE_TEST_UV_CACHE_DIR to that directory when running pytest or tox. This reuses dependency downloads only: each test still builds the real wheels, creates a fresh consumer environment, copies installed files, and probes the public SDK outside the checkout. It does not disable dependency resolution or make the test offline. Each build, install, and probe has a ten-minute timeout. Reuse follows uv’s cache-safety contract; do not manually change files inside that cache.

For dependency-only changes, also run uvx --from pip-audit pip-audit --local --progress-spinner off and pnpm audit --prod from docs/astro-site.

Before starting a local gate in a shared checkout, check whether another task already owns a running tox process and its result log. Coordinate reuse of that run instead of launching a second process against the same .tox directory. Use the same tox executable and interpreter for follow-up environments: mixing global and repository-managed tox processes can recreate each other’s caches. If an independent run is necessary, give it a separate work directory. Do not stop another task’s process or treat its pending result as a pass.

Dependency and experimental-feature policy

The supported Python 3.12–3.14 range tracks compatible stable dependencies and commits uv.lock for reproducibility. Before dependency or runtime changes, run uv lock --upgrade and python scripts/dependency_frontier.py . --strict.

Apache Arrow/Parquet is the canonical public tabular interchange; JSON Lines is an explicit human-debug format. Experimental serializers, JAX, NumPyro, accelerators, and distributed runtimes remain behind named extras and require round-trip, numerical-equivalence, provenance, and CPU-reference evidence before promotion. Python free-threading remains an observation lane rather than a release or performance claim.

Standardized-ingestion benchmarks use generated, bounded local fixtures and record stages, input dimensions, and memory rather than enforcing elapsed-time budgets. They cover only the strict Croissant CSV and Frictionless local CSV/JSON/Parquet/Arrow profiles; they are not evidence about network transport, remote catalogues, or upstream parser performance.

GitHub gates

The hosted repository runs CodeQL, OpenSSF Scorecard, Dependency Review, and Zizmor. Workflows also enforce SHA-pinned actions, least-privilege permissions, disabled credential persistence on security-sensitive checkouts, and release artifact provenance attestations. The release workflow also publishes the signed SLSA bundle as a .intoto.jsonl release asset so independent tools can discover provenance without privileged access to GitHub’s attestation store.

The protected main ruleset requires pull requests, resolved review threads, successful required checks, signed commits, and linear history. The required approval count is zero for the single-maintainer operating model; CODEOWNERS still routes review responsibility without creating an impossible independent approval gate. Hosted settings must be verified through the GitHub API because they are not represented by files in the checkout.

OpenSSF’s aggregate Scorecard is interpreted check by check. Independent human review and multi-organisation contributor diversity are useful signals, but a single-maintainer project cannot manufacture either signal. The repository therefore retains zero required approvals while requiring the complete automated matrix, signed commits, current branches, resolved threads, and immutable releases. Those deliberate exceptions should not be bypassed with bot approvals, alternate accounts, synthetic contributors, or placeholder releases.

GitHub immutable releases should be enabled in hosted repository settings so published release assets and their tag cannot be modified.

TestPyPI promotion requires exact SHA-256 equality with the privately reviewed release payload, GitHub build-provenance verification, cryptographic attestation verification, and clean-install smoke tests on every supported Python version. Because the attestation client’s direct-URL mode accepts only the production distribution host, the workflow retrieves each provenance object from TestPyPI’s Integrity API and verifies it against the corresponding reviewed local distribution. Integrity API, identity, digest, signature, and certificate errors all fail closed.

Owner and organization gates

Some controls cannot be configured from this repository alone:

• organization-wide Actions policies, runner groups, and required workflows;
• billing- or plan-dependent secret-scanning validity checks;
• enterprise security policy and outside-collaborator restrictions;
• environment reviewers and production deployment approvals.

These remain administrator-owned follow-up gates and must not be represented as locally complete merely because repository workflows pass.