Skip to content

CI/CD Pipeline

Zenith scaffolds automation using GitHub Actions, organizing delivery and maintenance into two distinct operational lifecycles: a continuous delivery pipeline triggered by code changes, and a scheduled governance pipeline running background security audits.

Delivery Pipeline

flowchart LR
    Code["Push / Pull Request"] --> PR
    PR -->|Merge to main| Main

    subgraph PR["Pull Request Gate"]
        direction TB
        Tests["python_tests.yaml<br/>Static Quality, Matrix & 100% Coverage"]
        Smoke["test_redistribute.yaml<br/>Isolated Wheel Installation Smoke"]
        Tests --> Smoke
    end

    subgraph Main["Main Branch Delivery"]
        direction TB
        Docs["docs.yaml<br/>Verified Docs & llms.txt"]
        Sync["sync-example.yaml<br/>Downstream Showcase Canary"]
        Pub["publish.yaml<br/>PyPI Trusted Publishing (Release Tags)"]
        Docs ~~~ Sync ~~~ Pub
    end

Python Test Workflow

Guarantees code correctness, strict typing, architectural boundaries, and cross-version compatibility across Python 3.12 through 3.15.

Automated quality gates block syntax flaws, unannotated functions, cyclomatic complexity spikes, circular imports, and undeclared dependencies before human review begins. Mandatory 100% statement and branch coverage enforces complete assertion depth, lowest-direct resolution proves that declared minimum dependency bounds in pyproject.toml actually work, and UV_EXCLUDE_NEWER establishes an explicit package cutoff timestamp to shield builds against upstream supply-chain disruptions.

Test Redistribution Workflow

Proves that built wheel (.whl) and source (.tar.gz) distribution packages install and execute cleanly in isolated user environments.

Tests run inside a developer checkout often pass because uncommitted files or assets exist locally on disk. Installing freshly built wheels into an isolated environment and executing tests against the installed artifact eliminates local checkout blind spots, proving that users installing via uv add or pip install receive a fully functional distribution.

Documentation Workflow

Builds and deploys verified documentation to GitHub Pages while compiling machine-readable llms.txt feeds for AI assistants.

Strict build-time validation eliminates link rot by failing deployments whenever an internal link, API reference anchor, or footnote is broken. The workflow deploys credential-free via GitHub OpenID Connect (OIDC) permissions, while automatically compiling structured site/llms.txt and site/llms-full.txt feeds for AI coding assistants.

Important

Configure GitHub Pages Deployment Source

In newly created GitHub repositories, you must explicitly configure GitHub Pages to deploy from Actions:

  1. In your repository on GitHub, navigate to Settings → Pages.
  2. Under Build and deployment → Source, select GitHub Actions (not "Deploy from a branch").

Without this setting, the deploy job in docs.yaml will fail with an authorization error when pushing to main.

Showcase Synchronization Workflow

Automatically instantiates the template with canonical context on every push to main and synchronizes the rendered project to the live downstream repository (bwrob/zenith-example).

Template updates can subtly introduce broken syntax or invalid configurations that isolated unit tests miss. Instantiating and pushing a real repository acts as a continuous integration canary for template health, while providing external developers with a browsable, tested reference implementation.

Publishing Workflow

Publishes signed wheel and source packages to PyPI with cryptographic build provenance attestations whenever developers push a release tag.

PyPI Trusted Publishing (OpenID Connect) authenticates the release without long-lived API tokens or passwords stored in repository secrets. Cryptographic build provenance attestations generated via GitHub Attestations give consumers mathematical proof that release artifacts originate directly from the verified source commit without tampering.

Scheduled Governance

flowchart LR
    Cron["Weekly Schedule (Cron)"] --> Audit

    subgraph Audit["Scheduled Vulnerability Scan"]
        direction TB
        Scan["guard-dependencies.yaml<br/>uv audit Transitive Lockfile Inspection"]
        Alert["Security Alert<br/>Actionable CVE Advisory Notification"]
        Scan -->|Vulnerability Detected| Alert
    end

Dependency Guard Workflow

Continuously audits locked transitive dependencies against published CVE vulnerability databases on a recurring schedule.

Security vulnerabilities are frequently uncovered in third-party packages months after dependencies are locked and deployed. Running scheduled background audits alerts maintainers to newly disclosed CVEs, enabling prompt remediation before vulnerabilities affect production services.