CI CD

Architect CI/CD as Separate Jobs with Trusted Publishing

A Python package without CI is a Python package with bugs you discover after release. Every serious package -- FastAPI, Pydantic, httpx, Ruff, uv, Polars -- follows the same five-stage pipeline: lint, type-check, test, build, publish. These stages run as separate jobs, not steps, because separate jobs enable parallel execution, clear failure attribution, and conditional downstream gates. The publish job uses OIDC trusted publishing with zero long-lived secrets -- API tokens are a supply chain risk that PyPI's trusted publishing eliminates entirely.

Workflow Architecture

Structure every CI pipeline as a dependency graph of discrete jobs:

  lint + type-check   (parallel)
        |
      tests           (matrix: Python versions x OS)
        |
      build           (sdist + wheel, upload artifact)
        |
     publish          (trusted publishing, environment protection)

Test Matrix

Run the full Python version matrix on Linux. Add macOS and Windows only if your package has platform-specific behavior (path handling, native extensions, OS-specific dependencies). When cross-platform testing is needed, test oldest + newest Python versions only to keep CI costs manageable.

strategy:
  fail-fast: false
  matrix:
    python-version: ["3.10", "3.11", "3.12", "3.13"]
    os: [ubuntu-latest]
    include:
      # Add these only if your package has platform-specific behavior
      - { python-version: "3.10", os: macos-latest }
      - { python-version: "3.13", os: macos-latest }
      - { python-version: "3.10", os: windows-latest }
      - { python-version: "3.13", os: windows-latest }

Upload coverage from a single matrix entry (latest Python, Linux) to avoid duplicate reports.

Trusted Publishing (OIDC)

Publish to PyPI with zero secrets. The pypa/gh-action-pypi-publish action handles the OIDC token exchange automatically. No password, no user, no PYPI_API_TOKEN. See the security-supply-chain skill for the threat model and broader supply chain hardening context.

Setup on PyPI: Project Settings > Publishing > Add trusted publisher with owner, repo, workflow filename, and environment name. For new packages, use a "pending publisher" at pypi.org/manage/account/publishing/.

Required permissions on the publish job:

permissions:
  id-token: write       # OIDC token exchange
  attestations: write   # Sigstore attestations
  contents: read

GitHub environment: Create a release environment in Repository Settings > Environments. Add branch protection rules limiting to main or v* tags.

Caching

Use astral-sh/setup-uv@v5 with enable-cache: true in every job. This single line caches uv's global package cache keyed on the lock file.

- uses: astral-sh/setup-uv@v5
  with:
    enable-cache: true
    cache-dependency-glob: "uv.lock"

For legacy pip projects, use actions/setup-python@v5 with cache: "pip".

Release Automation

Trigger releases from GitHub Release events, not tag pushes. GitHub Releases provide a UI for release notes, drafts, and deliberate publishing.

on:
  release:
    types: [published]

Use hatch-vcs for version-from-tag: tag v1.2.3 produces version 1.2.3. Requires fetch-depth: 0 in the checkout step.

Configure auto-generated release notes in .github/release.yml:

changelog:
  categories:
    - title: "Breaking Changes"
      labels: ["breaking"]
    - title: "Features"
      labels: ["enhancement", "feature"]
    - title: "Bug Fixes"
      labels: ["bug", "fix"]
    - title: "Documentation"
      labels: ["docs"]
    - title: "Internal"
      labels: ["internal", "ci", "dependencies"]

Dependabot

Configure .github/dependabot.yml with both uv (or pip for non-uv projects) and github-actions ecosystems. Use groups to combine minor/patch updates into single PRs instead of one-PR-per-dependency.

version: 2
updates:
  - package-ecosystem: "uv"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      python-packages:
        patterns: ["*"]
        update-types: ["minor", "patch"]

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Note: Dependabot updates pyproject.toml but does not regenerate uv.lock. Add a CI step or post-update script to run uv lock after Dependabot PRs.

Use Renovate instead for monorepos, auto-merge rules, or when you need more granular control over update strategies.

Anti-Patterns

Reference Configuration

.github/workflows/ci.yml

name: CI
on:
  push:
    branches: [main]
  pull_request:
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with: { enable-cache: true }
      - run: uv run ruff check src tests
      - run: uv run ruff format --check src tests

  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with: { enable-cache: true }
      - run: uv run mypy src
      # For libraries, also run pyright (see code-quality skill)
      # - run: uv run pyright src

  test:
    needs: [lint, type-check]
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
        os: [ubuntu-latest]
        include:
          # Add these only if your package has platform-specific behavior
          - { python-version: "3.10", os: macos-latest }
          - { python-version: "3.13", os: macos-latest }
          - { python-version: "3.10", os: windows-latest }
          - { python-version: "3.13", os: windows-latest }
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with: { enable-cache: true }
      - run: uv run --python ${{ matrix.python-version }} pytest --cov --cov-report=xml
      - if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
        uses: codecov/codecov-action@v5
        with: { token: "${{ secrets.CODECOV_TOKEN }}", files: coverage.xml }

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: astral-sh/setup-uv@v5
        with: { enable-cache: true }
      - run: uv build
      - run: uvx twine check dist/*
      - uses: actions/upload-artifact@v4
        with: { name: dist, path: dist/, if-no-files-found: error }

.github/workflows/release.yml

name: Release
on:
  release:
    types: [published]

jobs:
  ci:
    uses: ./.github/workflows/ci.yml

  publish:
    needs: ci
    runs-on: ubuntu-latest
    environment: release
    permissions: { id-token: write, attestations: write, contents: read }
    steps:
      - uses: actions/download-artifact@v4
        with: { name: dist, path: dist/ }
      - uses: pypa/gh-action-pypi-publish@release/v1
        with: { attestations: true }

Review Checklist

When reviewing CI/CD configuration:

• Lint job runs ruff check and ruff format --check without --fix
• Type-check job runs mypy src (or pyright) in parallel with lint
• Test matrix covers Python 3.10-3.13 on Linux; oldest + newest on macOS/Windows only if platform-specific behavior exists
• fail-fast: false is set on the test strategy
• concurrency with cancel-in-progress: true prevents stale runs
• uv caching enabled via astral-sh/setup-uv with enable-cache: true
• Build job uses uv build + twine check + upload-artifact as separate step from publish
• Publish job uses pypa/gh-action-pypi-publish with OIDC -- no API tokens or secrets
• permissions: id-token: write is set on the publish job
• Sigstore attestations enabled with attestations: true
• GitHub release environment configured with branch protection rules
• fetch-depth: 0 set in checkout if using VCS-based versioning
• Dependabot or Renovate configured for both uv (or pip) and github-actions ecosystems
• Release triggered by on: release: types: [published], not raw tag push

Converted and distributed by TomeVault — claim your Tome and manage your conversions.