CircleCI (Workflow) の tags filter でドキュメントを誤読してハマった

CircleCI (Workflow) の tags filter で document を読み違えてハマったのでメモ。

Configuring CircleCI - CircleCI

CircleCI では filters 機構を用いて、tag/branch ごとに job の実行を制御することが可能。*1

例えば master branch のみで実行したい場合は

filters:
  branches:
    only: master

とすればよく、反対に master branch では実行したくない場合、

filters:
  branches:
    ignore: master

と記述すればよい。これは filters 指定がなければ デフォルトで全ての branch がjob実行対象 であることを意味している。

tags についてはどうなっているかというと

CircleCI does not run workflows for tags unless you explicitly specify tag filters. Additionally, if a job requires any other jobs (directly or indirectly), you must specify tag filters for those jobs.

Tags can have the keys only and ignore keys. You may also use regular expressions to match against tags by enclosing them with ‘/s’, or map to a list of such strings. Regular expressions must match the entire string. Both lightweight and annotated tags are supported.

- Any tags that match only will run the job.
- Any tags that match ignore will not run the job.
- If neither only nor ignore are specified then the job is skipped for all tags.
- If both only and ignore are specified the only is considered before ignore.

明示的に tags の設定をしないとタグは job 実行対象にならないと言っている。ここで v1.0.0 タグでのみ実行させる場合を考える。意味を深く考えずに branches の例を取るなら

filters:
  tags:
    only: v1.0.0

のようになるが、この表記の意味は 任意の branch 及び v1.0.0 タグのとき job 実行対象とする となってしまう。

したがって、v1.0.0 タグでのみ実行させる場合は以下のように 全ての branch を実行対象としないように記述する 必要がある。

filters:
  tags:
    only: v1.0.0
  branches:
    ignore: /.*/

ちなみに以下でも any branch で job が実行されてしまう。

filters:
  tags:
    only: v1.0.0
  branches:
    only: []

久々に tags を使おうとしてハマりまくってしまった・・・ちゃんと読むとたしかにそう書いてあるんだけど。なんとなく「指定する == 絞り込み」みたいな感覚だった。

filters:
  tags:
    run: true
  branches:
    run: false

みたいな書き方ができると嬉しいなぁ！

そういえば tags を必要とする workflow の実行したい jobs には全てこの filters をつけないといけないのがつらいけど、placeholder job を作って、そいつに filters を設定し、その job を始点とするような job tree を書けばいいんじゃないんですかね(動くかは知らない)

*1:余談ではあるが、workflow-level filtering が欲しい