Serapeum GitHub Actions

Reusable composite GitHub Actions for Python CI/CD workflows. Cross-platform (Windows, macOS, Linux), supporting pip, uv, and pixi package managers.

📚 Full documentation: https://serapeum-org.github.io/github-actions/

The docs site (built with MkDocs + mike versioning, deployed from this repo) covers every action in depth — inputs, outputs, examples, and the consumer contract for each. This README is a top-level index.

Actions

Python Setup

Set up Python with your preferred package manager, install dependencies, and configure caching. All three share the same install-groups input shape (PEP 735 groups and/or extras) and lock-file verification defaults.

Action	Usage	Guide	Reference
pip	serapeum-org/github-actions/actions/python-setup/pip@pip/v1	guide	reference
uv	serapeum-org/github-actions/actions/python-setup/uv@uv/v1	guide	reference
pixi	serapeum-org/github-actions/actions/python-setup/pixi@pixi/v1	guide	reference

Documentation

Action	Usage	Guide	Reference
mkdocs-deploy	serapeum-org/github-actions/actions/mkdocs-deploy@mkdocs/v1	guide	reference

mkdocs-deploy builds and publishes a versioned MkDocs site to GitHub Pages via mike. Version deployed is selected by the trigger input — pull_request → develop, main → main (default), release → the tagged version (with a configurable alias, e.g. latest).

New in mkdocs/v1.2.0 — notebooks-exclude and notebooks-continue-on-error skip or tolerate notebooks that can't run in a clean CI runner (live data, missing extras, flaky), so one failing notebook no longer aborts the deploy. Built on the opt-in notebook execution with caching added in mkdocs/v1.1.0: set notebooks-path: 'docs/notebook' and the action will walk your notebook tree, restore .jupyter_cache/ from actions/cache (keyed on notebook contents + src/**/*.py + pyproject.toml), preflight that jupyter/nbconvert/ipykernel are importable, execute uncached notebooks via jupyter nbconvert --execute, and feed the populated outputs into mkdocs-jupyter (which runs with execute: false). Omitting notebooks-path (the default) skips notebook execution entirely — zero behaviour change for existing consumers. See the notebook-execution section of the guide for the consumer contract (required deps, mkdocs-jupyter config, src-layout assumption, concrete pyproject.toml snippet).

Release

Action	Usage	Guide	Examples
GitHub Release	serapeum-org/github-actions/actions/release/github@github-release/v1	guide	examples
PyPI Release	serapeum-org/github-actions/actions/release/pypi@pypi-release/v1	guide	examples

The release/github action automates version bumping via Commitizen, writes the changelog incrementally from the source of truth, creates a git tag, and publishes a GitHub Release whose body is extracted directly from the changelog (so release notes and project changelog stay in sync).

Quick Start

name: CI

on: [push, pull_request]

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

      - uses: serapeum-org/github-actions/actions/python-setup/uv@uv/v1
        with:
          python-version: '3.12'
          install-groups: 'groups: dev test'

      - run: pytest

Deploy docs (with notebook execution) on every PR, main push, and release:

- uses: serapeum-org/github-actions/actions/mkdocs-deploy@mkdocs/v1
  with:
    trigger: ${{ github.event_name }}
    deploy-token: ${{ secrets.GITHUB_TOKEN }}
    notebooks-path: 'docs/notebook'

Dependency Groups Format

The install-groups input (for pip and uv) supports:

# PEP 735 dependency groups
install-groups: 'groups: dev test'

# Optional dependencies (extras)
install-groups: 'extras: aws viz'

# Both combined
install-groups: 'groups: dev, extras: aws'

For pixi, use the environments input instead:

environments: 'default py312'

Versioning

Each action is versioned independently with namespaced tags:

pip/v1.1.1      pip/v1       # Python setup with pip
uv/v1.2.1       uv/v1        # Python setup with uv
pixi/v1.2.1     pixi/v1      # Python setup with pixi
mkdocs/v1.3.1   mkdocs/v1    # MkDocs deploy
github-release/v1.5.0        github-release/v1
pypi-release/v1.0.3          pypi-release/v1

Pin to a major-version tag for automatic patch/minor updates, pin to an exact patch for reproducibility, or pin to a commit SHA for supply-chain hardening:

# Auto-update within v1 (recommended for most consumers)
uses: serapeum-org/github-actions/actions/python-setup/uv@uv/v1

# Exact patch (for reproducibility)
uses: serapeum-org/github-actions/actions/python-setup/uv@uv/v1.2.1

# Commit SHA (immutable — survives tag retagging)
uses: serapeum-org/github-actions/actions/python-setup/uv@38c111084f99d5ff5f4a1e63bedce48fe33a10c0  # uv/v1

Current versions and rolling-v1 commit SHAs

For SHA-based pinning, here is the latest release of each action and the commit its …/v1 rolling tag resolves to today. Update these when you bump a tag.

Action	Latest version	Rolling tag	Commit SHA
actions/python-setup/pip	pip/v1.1.1	pip/v1	38c111084f99d5ff5f4a1e63bedce48fe33a10c0
actions/python-setup/uv	uv/v1.2.1	uv/v1	38c111084f99d5ff5f4a1e63bedce48fe33a10c0
actions/python-setup/pixi	pixi/v1.2.1	pixi/v1	38c111084f99d5ff5f4a1e63bedce48fe33a10c0
actions/mkdocs-deploy	mkdocs/v1.3.1	mkdocs/v1	38c111084f99d5ff5f4a1e63bedce48fe33a10c0
actions/release/github	github-release/v1.5.0	github-release/v1	38c111084f99d5ff5f4a1e63bedce48fe33a10c0
actions/release/pypi	pypi-release/v1.0.3	pypi-release/v1	38c111084f99d5ff5f4a1e63bedce48fe33a10c0

To verify locally: git rev-parse <tag>^{commit} (the ^{commit} is required — git rev-parse <tag> returns the annotated-tag object SHA, not the commit it points at).

See the Versioning Guide for release workflow, tag conventions, and breaking-change policy.

Documentation

• Hosted docs: https://serapeum-org.github.io/github-actions/ (MkDocs, versioned via mike — includes latest, main, and per-release tags).
• In-repo guides: under docs/ — same content as the hosted site.
• Action reference pages: auto-generated from each action.yml into docs/reference/ by scripts/generate_action_docs.py (runs in CI on every push to main that changes an action).
• Getting Started: docs/getting-started.md.

Contributing

1. Read the test workflows in .github/workflows/test-*.yml to understand how each action is exercised.
2. Use test fixtures under tests/data/ — never hand-roll inline fixtures.
3. Maintain cross-platform compatibility (shell: bash, forward-slash paths, string-typed booleans).
4. Every test job that invokes an action whose code path can reach git push, mike deploy, gh release create, or PyPI upload MUST call ./.github/workflows/test-helpers/setup-fake-remote between actions/checkout and the first action invocation — pushes must never escape to the real GitHub repo.
5. Follow semantic versioning: new optional input = MINOR; behaviour-preserving fix or docs = PATCH; removed/renamed input or changed default behaviour = MAJOR.

License

See LICENSE for details.