README修正だけでpytestを走らせない。GitHub Actionsのpaths-ignoreを設定する

はじめに

GitHub Actionsで、pushするたびにpytestを実行するようにしていました。

on:
  push:
  pull_request:

コードを変更したときは便利ですが、READMEの誤字を直しただけでもテストが実行されます。

README.mdを修正
    ↓
GitHub Actionsを起動
    ↓
依存パッケージをインストール
    ↓
pytestを実行

そこで、Markdownやドキュメントだけを変更した場合は、Workflowを起動しないようにしました。

paths-ignoreを追加する

変更前の設定は次のとおりです。

.github/workflows/pytest.yml

name: pytest

on:
  push:
  pull_request:

paths-ignoreを追加します。

.github/workflows/pytest.yml

name: pytest

on:
  push:
    paths-ignore:
      - "**.md"
      - "docs/**"

  pull_request:
    paths-ignore:
      - "**.md"
      - "docs/**"

これで、変更されたファイルがすべて次のどちらかに該当する場合、Workflowは実行されません。

Markdownファイル
docsディレクトリ内のファイル

GitHub Actionsでは、変更されたすべてのパスがpaths-ignoreに一致した場合にWorkflowがスキップされます。一つでも一致しないファイルが含まれていれば、通常どおり実行されます。

実際の動作

READMEだけを変更した場合です。

README.md

この場合はpytestを実行しません。

一方、READMEとPythonコードを同時に変更した場合はどうでしょうか。

README.md
src/main.py

src/main.pyは除外対象ではないため、pytestが実行されます。

つまり、paths-ignoreは「このファイルが含まれていたら実行しない」ではありません。

変更されたファイルがすべて除外対象
    → 実行しない

除外対象ではないファイルが一つでもある
    → 実行する

pathsを使う方法

反対に、Python関係のファイルが変更された場合だけ実行する方法もあります。

on:
  push:
    paths:
      - "**.py"
      - "pyproject.toml"
      - "requirements*.txt"
      - ".github/workflows/pytest.yml"

  pull_request:
    paths:
      - "**.py"
      - "pyproject.toml"
      - "requirements*.txt"
      - ".github/workflows/pytest.yml"

この設定では、指定したパスのうち一つ以上が変更された場合にWorkflowが実行されます。

用途の違いは次のとおりです。

paths-ignore
    → 一部のファイルだけ除外したい

paths
    → 実行対象を明確に限定したい

同じイベント内でpathsとpaths-ignoreを同時に指定することはできません。含めるパターンと除外するパターンを併用したい場合は、paths内で!を使います。

Workflowファイル自身も対象にする

pathsで実行対象を限定する場合は、Workflowファイル自身も含めておくと安全です。

paths:
  - "**.py"
  - "pyproject.toml"
  - ".github/workflows/pytest.yml"

これを入れないと、pytestのWorkflowを変更しても、その変更を含むWorkflowが実行されない場合があります。

required checkにしている場合は注意

ブランチ保護で、このWorkflowをrequired checkに設定している場合は注意が必要です。

パスフィルターによってWorkflow全体がスキップされると、対応するチェックがPendingのままになり、Pull Requestをマージできない場合があります。

Workflowをパスフィルターでスキップ
    ↓
required checkがPending
    ↓
マージできない

個人リポジトリや、required checkにしていないWorkflowでは、単純なpaths-ignoreで十分です。

required checkとして利用する場合は、Workflow自体は起動したうえで、ジョブ単位の条件分岐を使う構成も検討する必要があります。条件によってスキップされたジョブは、成功扱いとして報告されます。

まとめ

READMEやドキュメントだけの修正でpytestを実行したくない場合は、paths-ignoreを追加できます。

on:
  push:
    paths-ignore:
      - "**.md"
      - "docs/**"

  pull_request:
    paths-ignore:
      - "**.md"
      - "docs/**"

非常に小さな設定ですが、ドキュメント更新のたびに不要なCIが動くことを防げます。

ただし、required checkとして利用しているWorkflowでは、スキップ時のPending状態に注意が必要です。

「何でも自動実行する」だけでなく、「必要な変更のときだけ実行する」ことも、CIを運用するうえでは重要だと感じました。