GitHub Actions で特定のディレクトリが更新された時にワークフローを実行する

#GitHub Actions

今回はGitHub Actions で特定のディレクトリでファイルの更新などが発生した時にGitHub Actions のワークフローを実行させる方法について説明します。

若葉香月

13 September, 2023

前提条件

GitHub のアカウントを持っていること

GitHub Actions のパス関連のトリガーについて

GitHub Actions のPush トリガーでは、特定のファイルやディレクトリ配下の更新を判断してワークフローを実行させることができます。また、特定のファイルやディレクトリ配下の更新を除外することもできます。アプリケーションの更新のみを見てワークフローを実行させたい、特定のファイルやディレクトリ配下の更新ではワークフローを実行させたくない、などの時にパスフィルターを利用できます。

GitHub Actions で特定のファイルやディレクトリ配下の更新を見てワークフローを実行するにはpaths を利用し、特定のファイルを除外したい場合はpaths-ignore を利用します。

特定のファイル・ディレクトリ配下で更新があった場合

特定のファイルやディレクトリ配下で更新があった場合のみワークフローを実行させたい場合は、paths を利用します。実行例では、src ディレクトリ配下のファイルまたはpackage.json が更新された場合にワークフローを実行させます。複数のファイル、パスを設定した場合、設定されたパスのいずれかで更新があればワークフローが実行されます。

# 特定のファイル・ディレクトリ配下で更新があった場合にワークフローを実行させる
on:
  push:
    paths:
      # srcディレクトリ配下のファイルが更新された時
      - 'src/**'
      # package.jsonが更新された時
      - 'package.json'

特定のファイル・ディレクトリ配下の更新を除外したい場合

特定のファイルやディレクトリ配下の更新を除外したい場合は、paths-ignore を利用します。実行例では、src ディレクトリ配下のファイルと.gitignore が更新された場合、ワークフローの実行しないようにします。

# 特定のファイル・ディレクトリ配下の更新を除外する
on:
  push:
    paths-ignore:
      # srcディレクトリ配下のファイルを除外する
      - 'src/**'
      # .gitignoreを除外する
      - '.gitignore'

上記は特定のパスとファイルを除外していますが、除外したファイル (ディレクトリ) と除外されてないパスで更新を行った場合、ワークフローは実行されるため更新には注意が必要です。また、メタデータファイルと除外したパスの更新を同時にpush してもワークフローは実行されます。

特定のファイル・ディレクトリの更新と除外を同時に行いたい場合

GitHub Actions のパスフィルターでは、paths とpaths-ignore を同時に利用することはできません。特定のファイル・ディレクトリの更新と除外を同時に設定したい場合はpaths と「!」を利用します。実行例ではsrc ディレクト配下が更新された時にワークフローを実行し、package.json が更新された時は除外するようにしています。

# 特定のファイル・ディレクトリの更新と除外を同時に行いたい場合
on:
  push:
    paths:
      # srcディレクトリ配下のファイルが更新された時
      - 'src/**'
      # package.jsonを除外する
      - '!package.json'

paths で更新と除外を同時に指定した場合に両方の条件を満たしても、更新された時の条件を満たしていれば除外の条件に一致してもワークフローは実行されます。

パスフィルターの注意点

GitHub Actions のパスフィルターについて、ドキュメントでは以下のケースに当てはまる場合、想定した挙動にならない可能性があります。Git diff には制限があり、コミット数が多すぎる場合、タイムアウトでdiff を生成できない場合にはワークフローが実行されます。

1,000 以上のコミットをプッシュする場合、あるいは GitHub がタイムアウトのために diff を生成できない場合、そのワークフローは常に実行されます。

diff の個数についても制限があり、以下の条件に一致する場合、ワークフローは実行されません。

diff は 300 個のファイルに制限されます。フィルターによって返された最初の 300 個のファイルに一致しないファイルが変更された場合、ワークフローは実行されません。ワークフローが自動的に実行されるように、より具体的なフィルターを作成する必要がある場合があります。

まとめ

GitHub Actions のトリガーで特定のファイル、ディレクトリの更新を判断したい場合はpaths を利用する
GitHub Actions のトリガーで特定のファイル、ディレクトリの更新を除外したい場合はpaths-ignore を利用する
更新と除外を同時に利用したい場合はpaths と「!」を利用する

参考資料

GitHub Actions のワークフロー構文