コンテンツへスキップ

Python 向け GitHub Actions ワークフロー テンプレート

最終更新

これは Python プロジェクト向けの動作する .github/workflows/ci.yml です。pip のダウンロードをキャッシュし、3 つの Python バージョンでテストし、ruff で lint を行い、pytest を実行します。Poetry または uv を使用している場合は、インストール手順を調整してください。

ワークフロー

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

分かりにくい部分の役割

  • バージョンは引用符で囲みます。 "3.11" は文字列にする必要があります。引用符のない 3.10 は、YAML では数値の 3.1 として読み込まれてしまいます。これは典型的なバグです。
  • cache: pip は、仮想環境ではなく pip のダウンロード キャッシュを保存します。キーは cache-dependency-path で指定したファイルから作成されます。省略すると、setup-python は requirements.txt のみを参照します。詳しくは pip のキャッシュ をご覧ください。
  • pip install ruff pytest は、このテンプレートを何も入っていないプロジェクトでも動くようにするための行です。開発用の requirements にすでに含まれている場合は、この行を削除してください。
  • permissions、concurrency、timeout-minutes は、すべてのテンプレートで使われている 3 つの安全設定です。読み取り専用のトークン、古くなったプルリクエストの実行のキャンセル、ジョブの実行時間の上限を設定します。
  • pytest -q はログを短く保ちます。デバッグ中に最初の失敗で停止させたい場合は -x を追加してください。

バリエーション

Poetry

pipx install poetry でPoetryをインストールし、setup-python で cache: poetry を使用し、poetry install --no-interaction を実行してください。コマンドは poetry run で実行します。

uv

astral-sh/setup-uv@v5 を enable-cache: true と併用し、その後 uv sync と uv run pytest を実行します。

モノレポ

ステップに working-directory: を指定するか、ジョブに defaults.run.working-directory を指定し、各パッケージの requirements ファイルを cache-dependency-path で指定します。影響を受けるパッケージだけを実行するように paths: フィルターを追加します。

データベースのテスト

services: ブロックで Postgres を追加します。完全な構成は Django テンプレート で確認できます。

デプロイジョブ

needs: test と if: github.ref == 'refs/heads/main' を指定して、2 つ目のジョブを追加します。python -m build で wheel をビルドし、先に 成果物 としてアップロードします。

macOS または Windows

両方で動作する必要があるライブラリを公開する場合は、マトリックスに os: [ubuntu-latest, windows-latest] を追加します。

より高速なマシンで実行する

テストスイートは処理時間のかかる部分になりがちです。次の 1 行を変更してください:

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

この変更により、ジョブは compiler.dev の新しい 8 vCPU マシン上で実行され、元のランナーへは自動的にフォールバックします。追加のコアを活用するには pytest-xdist(pytest -n auto)と組み合わせてください。pytest が遅くなる理由については こちら、料金については 料金ページ をご覧ください。

よくある質問

仮想環境もキャッシュすべきですか?

通常はおすすめしません。pip のダウンロードをキャッシュする方が安全です。キャッシュした仮想環境は、Python のパッチバージョンが変わると動作しなくなることがあります。

プルリクエストでは 1 つの Python バージョンだけをテストするには?

main ではすべてのバージョンを対象にし、プルリクエストでは include を使って 1 つのバージョンだけを指定するマトリックスを使います。詳しくは マトリックスビルド をご覧ください。

pip install に時間がかかるのはなぜですか?

お使いの Python バージョン向けの wheel が存在しない場合、コンパイル済み拡張を含むパッケージはソースからビルドされます。wheel を提供しているバージョンに固定してください。

pytest を高速化できますか?

はい。コアを活用するには pytest-xdist、複数マシンに分散するには テストのシャーディング を使用してください。