Skip to content

workflows

This directory contains the GitHub Actions workflows that define the Continuous Integration and Continuous Deployment (CI/CD) pipelines for the project. These pipelines automate code testing, package publication, and documentation generation.

All workflows in this directory share a common foundation: they use Astral's uv for extremely fast Python environment setup and dependency synchronization, and they run the test suite across multiple supported Python versions (3.11, 3.12, and 3.13).

Workflow Details

Continuous Integration

The main quality gate is defined in test.yml.

  • Triggers: Runs on every push and pull_request to the repository.
  • Process: It sets up a matrix for Python 3.11, 3.12, and 3.13, syncs the project dependencies using uv sync --locked --dev, and runs the test suite via uv run pytest. This ensures that no code modifications break existing functionality across any of the targeted Python environments.

Package Publishing

The distribution pipeline is defined in publish.yml.

  • Triggers: Runs when a new GitHub release is created.
  • Process:
    1. First, it runs the standard test matrix to guarantee the release candidate is stable.
    2. Upon successful testing, it leverages Trusted Publishers (OIDC authentication) to securely build and upload the Python package to PyPI using uv build and uv publish.

Documentation Deployment (Self-Documentation)

The documentation generation and hosting pipeline is defined in publish_site.yml. This workflow showcases a "dogfooding" pattern where the tool documents itself.

  • Triggers: Runs when a new release is created, or when manually triggered via workflow_dispatch.
  • Process:
    1. It runs the full matrix test suite to verify the code base before documenting it.
    2. It sets up caching for MkDocs Material assets to speed up builds.
    3. It runs the command-line interface of this library itself: uv run repo-guide . --gh-deploy .... This command scans the repository, leverages Google's Gemini LLM (using the LLM_GEMINI_KEY repository secret) to analyze the code and generate explanation guides, builds an MkDocs site, and deploys it directly to GitHub Pages.