GitHub Actionsでテストを自動化

投稿日：

2026-09-24

Python ライブラリのテストを GitHub Actions で自動化したので、コード例を用いてコマンドの役割などについて説明していきます。

ファイル作成

まずは、リポジトリ直下に .github/workflows フォルダを作成し、そこに yaml または yml ファイルを作成します。

トリガー条件と権限設定

トリガー条件は必須ですが、権限設定は任意です。

name: CI

on: 
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

name

ワークフローの名前を設定します。
省いた場合はリポジトリルートからの相対パスになります。
Actions タブの中にこの名前が表示されます。

on

トリガー条件を指定します。
この例では、main ブランチに対して push・PR 時に発動するようになっています。

push.<branches|tags|branches-ignore|tags-ignore>

push 時にどのブランチやタグで実行するかを設定します。
例えば、main ブランチ、または v2 タグが push された時に実行する場合はこのように書きます。

on:
    push:
        branches: [main]
        tags: [v2]

<pull_request|pull_request_target>.<branches|branches-ignore>

特定のブランチを対象に PR（pull request）時に実行するのに使われます。

permissions

権限設定をします。
この例ではソースコードの読み取りのみ行うので、contents: read を指定しています。

ジョブ設定（jobs）

jobs:
  test:
    runs-on: ${{ matrix.os }}
    timeout-minutes: 10

    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        version: ["3.12", "3.13", "3.14"]

    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-python@v7
        with:
            python-version: ${{ matrix.version }}
            cache: pip
            cache-dependency-path: pyproject.toml

      - name: Install package and test dependencies
        run: python -m pip install . pytest

      - name: Run tests
        run: python -m pytest -q

jobs でワークフロー実行の構成を設定します。
複数のジョブはデフォルトで並列実行され、jobs は１つ以上を設定する必要があります。
各ジョブは、runs-on で指定されたランナー環境で実行されます。

<job_id> でジョブを識別するためのユニークな識別子を指定します。
英字または _（アンダーバー）で始まり、 英数字・-（ハイフン）・_（アンダーバー）のみを含んだ名前でなければいけません。
この例では test という識別子を指定しています。

runs-on

ジョブを実行するマシンを指定します。
この例ではクロスプラットフォームでテストするため、strategy.matrix で指定した OS を ${{ matrix.os }} で設定しています。

Linux の self-hosted runner で実行する場合は、runs-on: [self-hosted, linux] のように配列で渡します。

timeout-minutes

ジョブが GitHub によってキャンセルされる前の実行時間（分）を指定します。
デフォルトは 360 分です。
これはフリーズやループなどの状態になった場合、デフォルトの時間まで実行が続いてしまうため、明示的に最大時間を指定するために使われます。

strategy

ジョブのマトリックス戦略に使用します。
１つのジョブ定義には変数を使用して、変数の組み合わせに基づいて複数のジョブ実行を作成できます。これによって、複数バージョンの言語やオペレーションシステムでテストを実行できます。

fail-fast

マトリックス内のジョブのいずれかが失敗した場合に、実行・待機中のジョブが GitHub によって取り消されます。デフォルトは true です。
失敗しても全てのジョブを実行したい場合は false を指定します。

matrix

ジョブのマトリックスを定義します。
１つのマトリックスから展開されるジョブ数は最大 256個です。

この例では、os という変数に各 Ubuntu・Windows・macOS の最新版と、version という変数に Python のバージョンを指定しています。
これで、指定した OS × Python バージョン の全組み合わせのジョブが自動的に作成されます。

 matrix:
     os: [ubuntu-latest, windows-latest, macos-latest]
     version: ["3.12", "3.13", "3.14"]

steps

１つのジョブでステップごとにアクションを実行します。
各ステップは別のプロセスで実行されるので、あるステップ内で変更した環境変数は、次のステップには引き継がれません。変更したい場合は、env で設定します。

uses

ステップの一部として実行するアクションを選択します。

アクションは、再利用可能なコードの単位です。
この例では２つのアクションを選択しています。
actions/checkout@v7 で $GITHUB_WORKSPACE 配下のリポジトリの中身を取得します。このアクションを使用する場合は、認証トークンやSSH鍵を明示的に渡している以外は、読み取り権限を指定することが推奨されています。

permissions:
    contents: read

actions/setup-python@v7 で、特定の Python のバージョンをセットアップします。

with

アクションで定義されている入力引数と値のマップです。
Python のセットアップで使える入力引数はこちらで確認できます。

python-version では Python バージョンを指定できます。
この例では matrix で設定した変数を指定しています。

cache では、依存関係のキャッシュに使用するパッケージマネージャーを指定します。
この例では pip を指定しているため、pip のグローバルキャッシュディレクトリがキャッシュされます。

cache-dependency-path では、キャッシュキーの生成に使用する依存ファイルのパスを指定します。
ワイルドカードを使用して複数ファイルのパスを指定することも出来ます。

- uses: actions/setup-python@v7
    with:
        python-version: ${{ matrix.version }}
        cache: pip
        cache-dependency-path: pyproject.toml

name

GitHub で表示されるステップ名を指定します。
こんな感じで表示されます。

run

オペレーションシステムシェルを使用してコマンドライン（21,000 字以内）を実行します。
name でステップ名を指定してない場合は、このコマンドで指定されたテキストがステップ名として表示されます。
デフォルトでは非ログインシェルが使用されます。使用するシェルを明示的に選択したい場合は shell で指定します。

この例では、自分のパッケージと pytest をインストールしています。

- name: Install package and test dependencies
    run: python -m pip install . pytest

まとめ

GitHub Actions でのテスト自動化を解説しました。
PyPI へのリリースも自動化してるので、気になる方は release.yaml を見てみてください！

• メール
• GitHub
• Twitter