reusable-tox.yml: Five Patterns to Eliminate CI/CD Boilerplate

Maintaining CI/CD configurations across dozens of Python projects means copying the same tox invocations, Python version matrices, and error-handling logic into every repository. This poster presents five architectural patterns from the reusable-tox.yml project that eliminate this duplication by applying familiar software engineering principles to GitHub Actions workflows.

Each pattern is illustrated with a before/after YAML comparison and a Python code analogy, making the design decisions immediately recognizable to Python developers:

• Singular inputs — accepting one Python version per workflow call instead of JSON arrays. Like writing def run(version: str) instead of def run(versions: list[str]) — simpler to reason about, test, and compose via caller-side matrix strategies.
• Caller-side matrix strategy — separating "what to test" (the calling workflow's job) from "how to test" (the reusable workflow's job). The same Separation of Concerns you'd apply to Python modules.
• Three-phase execution — splitting tox runs into environment preparation (tox --notest), main execution, and debug rerun on failure. Like Unix pipelines — each stage transforms data through a single responsibility, improving cacheability and error diagnosis.
• Composite action hooks — providing extension points where projects inject custom setup logic without modifying shared infrastructure, discovered automatically via hashFiles(). The Dependency Injection pattern applied to CI/CD.
• Explicit over implicit — refusing to auto-detect tox environments or infer configuration. Predictable and debuggable beats magical and surprising.

The poster includes a "Which pattern solves your problem?" decision flowchart and a QR code linking to the open-source repository with ready-to-fork templates.

Born from maintaining dozens of Python projects including aiohttp, CherryPy, and pip-tools, these patterns treat CI/CD with the same architectural rigor as application code.