Zum Inhalt springen

Python GitHub Actions Workflow-Vorlage

Zuletzt aktualisiert am

Dies ist ein funktionierendes .github/workflows/ci.yml für ein Python-Projekt. Es cacht pip-Downloads, testet auf drei Python-Versionen, prüft den Code mit ruff und führt pytest aus. Passen Sie den Installationsschritt an, wenn Sie Poetry oder uv verwenden.

Der Workflow

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        python: ["3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
          cache: pip
          cache-dependency-path: |
            requirements*.txt
            pyproject.toml

      - run: python -m pip install --upgrade pip
      - run: pip install -r requirements.txt -r requirements-dev.txt
      - run: pip install ruff pytest
      - run: ruff check .
      - run: pytest -q

Was die nicht offensichtlichen Teile bewirken

  • Versionen in Anführungszeichen. "3.11" muss als Zeichenkette angegeben werden. Ohne Anführungszeichen liest YAML 3.10 als Zahl 3.1, ein klassischer Fehler.
  • cache: pip cacht den pip-Download-Cache, nicht die virtuelle Umgebung. Der Schlüssel wird aus den Dateien in cache-dependency-path gebildet. Wenn Sie diese Angabe weglassen, sucht setup-python nur nach requirements.txt. Siehe pip-Caching.
  • pip install ruff pytest ist enthalten, damit die Vorlage in einem schlanken Projekt läuft. Stehen beide Pakete bereits in Ihren Entwicklungsabhängigkeiten, können Sie die Zeile löschen.
  • permissions, concurrency und timeout-minutes bilden das Sicherheits-Trio, das in jeder Vorlage verwendet wird: schreibgeschütztes Token, Abbruch veralteter Pull-Request-Runs und ein Zeitlimit für Jobs.
  • pytest -q hält die Logs kurz. Fügen Sie -x hinzu, um beim Debuggen beim ersten Fehler anzuhalten.

Varianten

Poetry

Installieren Sie Poetry mit pipx install poetry und verwenden Sie dann cache: poetry in setup-python sowie poetry install --no-interaction. Führen Sie Befehle mit poetry run aus.

uv

Verwenden Sie astral-sh/setup-uv@v5 mit enable-cache: true, danach uv sync und uv run pytest.

Monorepo

Nutzen Sie working-directory: bei Schritten oder defaults.run.working-directory auf Job-Ebene und verweisen Sie cache-dependency-path auf die Requirements-Datei jedes Pakets. Mit einem paths:-Filter laufen nur die betroffenen Pakete.

Datenbanktests

Fügen Sie einen services:-Block mit Postgres hinzu; die Django-Vorlage zeigt das vollständige Muster.

Deploy-Job

Fügen Sie einen zweiten Job mit needs: test und if: github.ref == 'refs/heads/main' hinzu. Bauen Sie das Wheel mit python -m build und laden Sie es zuerst als Artefakt hoch.

macOS oder Windows

Ergänzen Sie os: [ubuntu-latest, windows-latest] in der Matrix, wenn Sie eine Bibliothek veröffentlichen, die auf beiden Systemen funktionieren muss.

Auf schnelleren Maschinen ausführen

Testsuiten sind oft der langsame Teil. Ändern Sie eine Zeile:

    runs-on: [self-hosted, Linux, compiler-ci]

Der Job läuft dann auf einer frischen Maschine mit 8 vCPUs von compiler.dev, mit automatischem Rückfall auf Ihren ursprünglichen Runner. Kombinieren Sie das mit pytest-xdist (pytest -n auto), um die zusätzlichen Kerne zu nutzen, und lesen Sie, warum pytest langsam ist und Preise.

FAQ

Sollte ich die virtuelle Umgebung cachen?

In der Regel nein. Das Cachen der pip-Downloads ist sicherer. Eine gecachte virtuelle Umgebung kann brechen, wenn sich die Patch-Version von Python ändert.

Wie teste ich bei Pull Requests nur eine Python-Version?

Verwenden Sie eine Matrix mit allen Versionen auf main und einer einzelnen Version bei Pull Requests, indem Sie include nutzen. Siehe Matrix-Builds.

Warum dauert pip install so lange?

Pakete mit kompilierten Erweiterungen werden aus dem Quellcode gebaut, wenn es kein Wheel für Ihre Python-Version gibt. Fixieren Sie Versionen, die Wheels bereitstellen.

Kann ich pytest beschleunigen?

Ja: pytest-xdist für mehr Kerne, Test-Sharding für mehr Maschinen.