はじめに
GitHub Actionsにおいて、 on: pull_request のときに追加で指定できる paths や paths-ignore の使い方がしょっちゅうこんがらがるので、具体例を並べて整理しました。
公式ドキュメントはこちら
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths
基礎知識の整理
pathsにマッチするファイルの変更が1個でもあったら、ワークフローを起動する。
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#example-including-paths
paths-ignoreにマッチするファイルの変更 しか なかったら、ワークフローを起動しない。
paths-ignoreにマッチしないファイルの変更が1個でもあったら、ワークフローを起動する。
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#example-ignoring-paths
1個のワークフローにおいて、pathsとpaths-ignoreは併用不可。
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#excluding-paths
pathsでは、 ! が使える。pathsに複数の値を指定するときに使える。
! 付きの指定（negative patternと呼ぶ）を含む場合は、値の順序が重要になってくる。「後勝ち」と覚えれば分かりやすい。
あるpositive patternの後ろにnegative patternを書くと、先のpositive部分から後のnegative部分を差し引いた指定になる。negative部分が「例外」と思えば良い。
あるnegative patternの後ろにpositive patternを書くと、後のpositive部分をやっぱり含める指定になる。positive部分が「例外の例外」と思えば良い。
具体例
まずは一番単純な例から。
# pathsもpaths-ignoreもないので、常に起動する。
on: pull_request
ベン図にするとこんな感じです。
pathsの単純な例はこちら。
# jsファイルの変更が含まれていたら、起動する。
on:
pull_request:
paths:
- '**.js'
pathsに複数の値を指定すると、ORになります。
# （jsファイルまたはmdファイル）の変更が含まれていたら、起動する。
on:
pull_request:
paths:
- '**.js'
- '**.md'
次はpaths-ignoreの単純な例。
# jsファイルの変更しか含まれていなかったら、起動しない。
# jsファイル以外の変更が含まれていたら、起動する。
on:
pull_request:
paths-ignore:
- '**.js'
paths-ignoreに複数の値を指定すると、ignoreする部分がORになります。
# （jsファイルまたはmdファイル）の変更しか含まれていなかったら、起動しない。
# （jsファイルまたはmdファイル）以外の変更が含まれていたら、起動する。
on:
pull_request:
paths-ignore:
- '**.js'
- '**.md'
今度はpathsにnegative patternを含めてみます。
on:
pull_request:
paths:
- 'module-a/**' # module-aディレクトリの子孫に変更があったら、起動する。
- '!**.md' # あっ、でも、mdファイルの変更はノーカンで。
続いて、negative patternの後にpositive patternを加えてみます。
on:
pull_request:
paths:
- 'module-a/**' # module-aディレクトリの子孫に変更があったら、起動する。
- '!**.md' # あっ、でも、mdファイルの変更はノーカンで。
- 'module-a/**/important.md' # あっ、でもでも、module-a子孫のimportant.mdの変更だったら、
# ノーカンにするのをやっぱ無しで。
まとめ
落ち着いて整理すると、そんなに難しくない気がしてきました。とはいえ、あまり複雑な指定をすると自分にしか解読できなくなりそうですので、ほどほどにしたいところです。
実用性はあまりないですが、paths-ignoreで表現できる集合はpathsでも表現できそうですね。全体集合（ ** ）から、negative patternで差し引いていくと。