CircleCI の CLI では "matrix" キー を用いたマトリックスビルドは実行できずにエラーになる

前提

以下のような .circleci/config.yml ファイルがあったとします。

version: 2.1

orbs:
  node: circleci/node@4.1.0

jobs:
  my_job:
    docker:
      - image: cimg/base:stable
    parameters:
      node-version:
        description: Node.js のバージョン
        type: string
        default: "14.0"
    steps:
      - checkout
      - node/install:
          node-version: << parameters.node-version >>
          install-yarn: true
      - run:
          command: node -v

workflows:
  my_workflow:
    jobs:
      - my_job:
          matrix:
            parameters:
              node-version: ["10.23.1", "12.16.0", "14.15.4", "15.6.0"]

上記の YAML ファイルでは、複数の Node.js のバージョン*1にて node -v が実行されることが期待されます。

結論

しかし、ローカルの CircleCI CLI で実行した場合には、以下のようなエラーが出て実行できません。

$ circleci local execute --job my_job
Docker image digest: sha256:......
====>> Spin up environment
Build-agent version  ()
Error:
Configuration errors: 1 error occurred:
        * Cannot find a job named `my_job` to run in the `jobs:` section of your configuration file.
If you expected a workflow to run, check your config contains a top-level key called 'workflows:'

理由は、公式ページ に書かれているとおりです。

CLI ツールでは、ワークフローの実行がサポートされていません。 基本的にワークフローは、複数のマシンで行うビルドの並列実行を活用することによって、高速で複雑なビルドを可能にします。 CLI はユーザーのマシンでのみ動作するため、単一の jobs (ワークフローを構成する一要素) しか実行できません。

matrix: キーは workflows: キー内でのみ用いることができるキーです。すなわち、CircleCI CLI ではワークフローの実行がサポートされていないため、matrix: キーを用いた実行もまたサポートされていないということになります。

補足

上記のような特徴があるため matrix: キーが含まれているジョブをローカルで実行する際は、同等の別の YAML ファイル(複数個になることでしょう)を作っておいてそれを実行する*2という方法を採るべきでしょう*3

感想

エラーメッセージの文面からこの理由を導き出すのは相当難しく、ハマりました……。

参考書籍

以下の書籍を参考にしました。巻末の設定ファイルキー一覧まとめが大変に役に立ちます。

gihyo.jp

以下は Amazon へのアフィリエイトリンクです。

*1:"10.23.1", "12.16.0", "14.15.4", "15.6.0"

*2:-c オプションを用いて明示的に別の YAML ファイルを指定する

*3:他に良い方法があれば知りたいところです

Powered by はてなブログ