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、複数マシンに分散するには テストのシャーディング を使用してください。
関連記事
- .NET GitHub Actions ワークフローテンプレートNuGet のキャッシュ、リストア、ビルド、テストの手順と SQL Server サービスの選択肢、同時実行制御と権限設定を備えた、.NET 向けの GitHub Actions CI をコピーしてすぐ使えます。
- Django GitHub Actions ワークフローテンプレートPostgres サービスコンテナー、pip キャッシュ、マイグレーションの確認とテストを備え、同時実行制御と権限設定も含む、Django 向けの GitHub Actions CI をコピーしてすぐ使えます。
- DockerビルドのGitHub ActionsワークフローテンプレートBuildx、GitHubのキャッシュレイヤー、mainへのプッシュ時のGHCRへのプッシュを使ってDockerイメージをビルドする、最小限の権限で動作するGitHub Actionsワークフローのコピー&ペースト用サンプルです。
- Elixir GitHub Actions ワークフローテンプレートPostgres サービスと、erlef/setup-beam による deps と _build のキャッシュ、フォーマットとテストを備えた、Elixir と Phoenix 向けの GitHub Actions CI をコピーしてすぐ使えます。