CI/CD Tooling¶

Shared GitHub Actions, reusable workflows, and pre-commit hooks for Python projects in the provide.io ecosystem.

Overview¶

The provide.io CI/CD Tooling provides standardized, battle-tested components for Python project automation:

GitHub Actions - Reusable composite actions for common CI/CD tasks
Workflows - Complete CI/CD pipelines as reusable workflows
Pre-commit Hooks - Code quality enforcement at commit time

Features¶

🚀 GitHub Actions¶

Composite actions for flexible CI/CD pipelines:

setup-python-env - Python, UV, and workenv setup
python-ci - Complete CI pipeline (quality + tests + build)
python-release - PyPI publishing and GitHub releases

🔄 Reusable Workflows¶

Complete end-to-end workflows:

python-ci.yml - Continuous Integration workflow
python-release.yml - Release automation workflow

🔍 Pre-commit Hooks¶

Automatic code quality enforcement:

provide-conform - SPDX headers and emoji footers (auto-detects repository)
provide-config-check - Validates ruff/mypy/pytest configurations

Quick Start¶

Using Actions¶

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run CI Pipeline
        uses: provide-io/ci-tooling/actions/[email protected]
        with:
          python-version: '3.11'
          coverage-threshold: 80

Using Reusable Workflows¶

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  ci:
    uses: provide-io/ci-tooling/.github/workflows/[email protected]
    with:
      python-version: '3.11'
      run-security: true

Using Pre-commit Hooks¶

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/provide-io/ci-tooling
    rev: v0.0.1
    hooks:
      - id: provide-conform
      - id: provide-config-check

Installation¶

Install Pre-commit Hooks Package¶

# Using pip
pip install provide-cicd

# Using uv
uv pip install provide-cicd

Set Up Pre-commit in Your Project¶

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml (see above)
# Install hooks
pre-commit install

Documentation Structure¶

Getting Started - Installation and setup guide
Actions - Individual GitHub Actions reference
Workflows - Reusable workflow documentation
Pre-commit Hooks - Pre-commit hook configuration
Design Documents - Architecture and design decisions

Design Philosophy¶

Convention Over Configuration¶

The tooling follows ecosystem conventions:

Source code in src/ directory
Tests in tests/ directory
Use workenv/ not .venv for virtual environments
Python 3.11+ as minimum version
UV as package manager
Ruff for linting and formatting
MyPy for type checking

Progressive Enhancement¶

Start simple and add features as needed:

Basic: Use python-ci action for complete pipeline
Custom: Compose individual actions for custom workflows
Advanced: Extend with additional steps and matrix testing

Zero-Friction Developer Experience¶

Auto-detection: provide-conform automatically detects repository
Sensible defaults: All actions work with minimal configuration
Clear feedback: Rich GitHub step summaries and error messages

Package Information¶

PyPI Package: provide-cicd
Import Path: from provide.cicd import ...
GitHub Repository: provide-io/ci-tooling
Documentation: foundry.provide.io/cicd

Support¶

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: This site