(こちらは Setup Workflows Open Preview の参考訳です。)
CircleCIに新たな機能 セットアップ・ワークフロー が加わりました。ワークフローをこれまでとは違った方法で活用するための機能です。
セットアップ・ワークフロー とは？
セットアップ・ワークフローとは、パイプラインを「セットアップ」するために実行されるワークフローです。CircleCIのジョブが、パイプラインのコンフィグやパラメータを生成、あるいは設定することで「セットアップ」を行います。
セットアップ・ワークフローにより実現可能となるユースケースとして、主に次の２つを想定しています。
- ダイナミック コンフィグ: 実行時にニーズに合うコンフィグを生成するようなスクリプトを定義できます。
- プレビルド ステップ: プレビルド ステップとして、実行時に何をビルドするのかを分析し、決定可能なステップを先行して実行できます。
セットアップ・ワークフローが有効であることが期待される領域の一つに、モノリポ(モノレポ)を活用いただいているお客様のサポートが挙げられます。Bazelのようなビルドツールを利用して、gitコマンドを実行して、変更のあったファイルを検出し、複雑な依存関係を分析した上で、複数あるコンフィグファイルを組み合わせて実行しているといった、さまざまなモノリポのユースケースにおいて、それぞれ異なるジョブを利用することが可能になります。各機能はOrbsの中に組み込んでおくことで、必要な機能を再利用することが容易になります。CircleCIでは、パス フィルタリングを行うOrbを今回リリースします。このOrbを使うことで、Push時にどのファイルが変更されたのかに応じて、パラメータを設定することが可能になります。例えば、どのワークフローを実行するのかを、引き続き実行されるワークフローに対してパラメータとして渡すことが可能になります。
動作する仕組みは？
-
セットアップ・ワークフローとは、setup パラメータを true に設定したワークフローです。.circleci/config.yml ファイル(のworkflows)には、セットアップ・ワークフローを１つ定義することが可能です。
-
(任意) Setup Workflow中のジョブでは、パイプライン変数を生成することが可能です。パイプライン変数を生成するには、シェルスクリプトをあらかじめ用意しておき、そのスクリプトで変数名と値をJSONファイルとして出力するようにします。
-
Setup Workflowではコンフィグを生成することが可能です。コンフィグを生成するには、次の３つの方法があります。
-
シェルスクリプトを用意しておき、スクリプト内でコンフィグをゼロから生成する。
-
コンフィグのパーツを個別のファイルとしていくつか用意しておき、ジョブ内で必要に応じてこれらのファイルを結合する(単一のファイルでコンフィグとして完結するのであれば、結合のためのジョブは不要)。
-
上記 1 と 2 を組み合わせる。
-
ワークフローの最後では、continuation orbからジョブを呼び出す必要があります。このジョブはセットアップ・ワークフロー実行時に生成されたパラメータファイル、コンフィグファイル、および継続キーを入力として、Continuation APIを呼び出します。それにより、API側でコンフィグをコンパイルし、その結果を渡されたパラメータと合わせて実行中のパイプラインに結合します(提供中のPath-filtering Orbはこの作業を自動的に実行してくれます)。
-
新たに生成、結合された後続パイプラインが引き続いて実行されます。
セットアップ・ワークフローを利用するには？
- (Project SettingsのAdvancedの中にある) Run Setup Workflows (PREVIEW) をトグルを右にしてtrueに設定します。
- (任意) セットアップ・ワークフローを試してみるためのブランチを新規作成します。
- (任意) 既存のconfig.ymlのバックアップをリネームするなどして、保存しておきます。
- .circleci/config.ymlを編集して、セットアップ・ワークフローを追加します。ここでは、コンフィグ／パラメータを生成するようなジョブを持つワークフローを作成します。
- (任意) コンフィグの中でパラメータを設定するのであれば、生成されるコンフィグの中で当該パラメータが定義されているか、確認します。
- このブランチをコミット／プッシュして、セットアップ・ワークフローの実行を開始します。
- (任意) セットアップ・ワークフロー用にブランチを作成していた場合は、デフォルトブランチにマージすることが可能です。
技術的な詳細に関しては、こちら(英文)のドキュメントをご参照ください。
Continuation Orb ドキュメント および ソースコード
パス フィルタリングを設定するには？
- 「セットアップ・ワークフローを利用するには？」に書かれた手順を実行します。
- .circleci/config.yml の中で Path-filtering Orbを使用するように定義します。
- filterジョブを使い、変更されたファイルのファイル名にマッチする正規表現とパイプライン パラメータのマッピングを定義します。
- (任意) 後で実行するために選択される、あるいは生成されるコンフィグの中で、当該パイプライン パラメータが定義されているか、確認します。
- 生成されたコンフィグがパイプライン パラメータを使ってコンフィグの実行をフィルタリングしているか確認します。
技術的な詳細に関しては、こちら(英文)のドキュメントをご参照ください。
Path-filtering Orb ドキュメント および ソースコード
よくいただくご質問
パイプライン パラメータが使用できるのはAPI経由での呼び出しの場合だけでは？
一般的にはそれが正しいです。ただし、セットアップ・ワークフローを使うことで、API経由の呼び出しであっても、webhook経由の呼び出し(つまりVCSからのプッシュであっても)、パイプライン パラメータを設定することが可能になります。
Continuation Orb／ジョブとは何ですか？
セットアップ・ワークフローはパラメータとコンフィグの生成に使われますが、そのためには、CircleCI側で、現在実行中の作業が完了したという通知を受け、実行中のパイプラインに、これから実行される内容を連結するしくみが必要になります。この目的を達成するため、Continuation APIという、パラメータとしてコンフィグを受け取り、実行完了時に連結するようなAPIが用意されました。Continuation API/ジョブはこのAPIをラップすることで、使いやすくしています。
Continuationとパス フィルタリングの観点から、sandboxとcircleci orbはどこが違いますか？
セットアップ・ワークフローのプレビュー初期では、sandbox/continuation Orbやsandbox/path-filtering Orbsを使用していましたが、これらのOrbsに関しては今後は更新されません。circleci orbs(circleci/continuation, circleci/path-filtering)に対して今後は更新を行っていきます。sandbox orbを使っているコンフィグがあるようでしたら、circleci orbに更新することを推奨いたします。