Release Certify

Release Certify proves that the exact Python artifact you are about to release passed your repository's declared quality, packaging, installation, and runtime checks.

uv tool install release-certify
cd your-python-project
release-certify

Prefer pipx? Install the same isolated command with:

pipx install release-certify

Release Certify reads release.evidence.yaml, runs every declared check, installs the release in a clean environment, verifies its public imports and startup command, and writes a deterministic certificate. Exit code 0 means the evidence was certified; exit code 1 means it was not.

It does not replace Ruff, MyPy, or pytest. It proves that all of them—and the installable result—agree that this release is ready.

Contract

This application example is ready to copy into release.evidence.yaml; replace the commands and import with your repository's actual release process.

release:
  kind: application

quality:
  lint:
    command: python -m ruff check .
  typing:
    command: python -m mypy .
  tests:
    command: python -m pytest -q

packaging:
  install:
    command: python -m pip install -r requirements.txt

runtime:
  smoke:
    - command: python app.py --help
      expected_exit: 0

imports:
  - my_app

artifact:
  type: source-tree

Run release-certify from the repository root. A failure identifies the missing proof and the next action.

Commands

release-certify
release-certify --verbose
release-certify --json
release-certify --output release_certificate.json
release-certify --root path/to/repository
release-certify inspect
release-certify inspect --json
release-certify --help
release-certify --version

Inspect repository evidence

release-certify inspect performs a read-only inspection and displays a non-authoritative starter contract when the existing deterministic inference can support one:

release-certify inspect
release-certify inspect --json
release-certify inspect --root path/to/repository

Inspection reports repository facts as OBSERVED, contract suggestions as INFERRED, and decisions that require an engineer as UNRESOLVED. It does not run certification, use cached evidence as proof, create a certificate, or claim release readiness. Suggested commands are unreviewed policy proposals even when repository tool configuration supports them. Inspection does not parse or execute CI workflows.

By default, inspection writes nothing. Copy the displayed proposed YAML into release.evidence.yaml only after reviewing it against the repository's actual release policy. When an explicit contract already exists, inspection reports it and does not propose a replacement. --output <path> explicitly writes inspection JSON; it never writes or overwrites release.evidence.yaml implicitly.

Evidence diagnostics

Use --verbose to inspect why category evidence was executed or reused, including deterministic cache fingerprints and invalidation reasons. When a freshly executed provider command fails, Release Certify displays a bounded excerpt of that provider's stdout and stderr. The provider output remains the provider's testimony; Release Certify does not reinterpret Ruff, MyPy, pytest, or arbitrary declared tools. Raw provider streams are not persisted in certificates or cache.

Release Certify remains evidence-driven and fail-closed: missing, invalid, ambiguous, or failed required evidence cannot produce a successful certificate.

What certification means

A successful certificate says EVIDENCE CERTIFIED: the declared commands passed for the byte-identified artifact in the recorded environment. It does not claim that those commands are adequate or that untested environments are safe. The Certificate Trust Model defines the exact guarantee and its limits.

Development

python -m pip install -e ".[dev]"
python -m ruff check .
python -m mypy src tests benchmarks tools
python -m pytest
python benchmarks/mutation_benchmark.py

See CONTRIBUTING.md for the contribution and pull-request process.