ダイナミックコンフィグの使用
このセクションでは、 ダイナミックコンフィグ を既にお読みになっていること、 入門ガイド ダイナミックコンフィグをはじめる に記載されている手順が実行済みであることを前提としています。
下記では、ダイナミックコンフィグの使用方法を説明します。
基本的な例
以下は、CircleCI のダイナミックコンフィグ機能を使用した基本的な例です。
この例では、generate-config スクリプトが既に存在することを前提としています。 このスクリプトは、行う処理の種類に基づいて新しい YAML 設定ファイルを出力します。
この過程で、git 履歴、パイプラインに渡される値、 ジョブ 内で行われる処理などの確認を行うことができます。
version: 2.1
# this allows you to use CircleCI's dynamic configuration feature
setup: true
# the continuation orb is required in order to use dynamic configuration
orbs:
continuation: circleci/continuation@0.1.2
# our defined job, and its steps
jobs:
setup:
executor: continuation/default
steps:
- checkout # checkout code
- run: # run a command
name: Generate config
command: |
./generate-config > generated_config.yml
- continuation/continue:
configuration_path: generated_config.yml # use newly generated config to continue
# our single workflow, that triggers the setup job defined above
workflows:
setup:
jobs:
- setup上記の設定ファイルは、以下のように設定されています。
-
設定ファイルの最上部に
setup: trueという行を追加して、CircleCI のダイナミックコンフィグ機能を使用するように指定します。 -
ダイナミックコンフィグ機能を使用するために
continuationOrb を呼び出します。 -
continuationOrb をexecutorとして使用するsetupというジョブを定義します。 このジョブでは、下記の処理を行います。 -
checkoutステップを呼び出して、設定されたリポジトリからコードをチェックアウトします。 -
runステップによりgenerate-configスクリプトを呼び出し、continuationOrb のcontinueジョブに受け渡すデータを生成します。 -
必須の
configuration_pathに指定された設定ファイルに基づいて、パイプラインの実行が続行されます。 -
最後に、
workflowにおいて、上記で定義されたsetupジョブを呼び出します。
ダイナミックコンフィグ機能を使用する場合、各 config.yml ごとに使用できるワークフローは 1 つのみです。 パイプラインのセットアップステージの一部として実行できるのは、1 つのワークフローのみです。 このセットアップ ワークフローには後続のワークフローを起動するためのワンタイムトークンが割り当てられます。 このセットアップ ワークフローはカスケードしないため、後続のワークフローが独自にさらに後に続くワークフローを起動することはできません。 |
continuation Orb の内容の詳細については、当該 Orb のソースコードを CircleCI Developer Hub で閲覧することや、 ダイナミックコンフィグの FAQ を参照することで確認できます。
変更されたファイルに基づいて特定の workflows または steps を実行する
workflow や step を実行するかどうかを、特定のファイルセットに対して行われた変更に応じて決定したい場合があります。 条件に応じた実行は、コードやマイクロサービスがモノレポ (単一のリポジトリ) に格納されている場合に役立ちます。
これを可能にするために、CircleCI には path-filtering Orb が用意されています。この Orb により、更新対象ファイルの具体的なパスに基づいて、パイプラインの実行を続行できます。
たとえば、以下のようなモノレポ構造を考えてみましょう。
├── .circleci
│ ├── config.yml
│ └── continue_config.yml
├── service1
│ ├── Service1.java
├── service2
│ ├── Service2.java
├── tests
│ ├── IntegrationTests.java上記のような状況におけるダイナミック コンフィグの実装例が、以下の config.yml および continue_config.yml です`:
config.yml
version: 2.1
# this allows you to use CircleCI's dynamic configuration feature
setup: true
# the path-filtering orb is required to continue a pipeline based on
# the path of an updated fileset
orbs:
path-filtering: circleci/path-filtering@0.1.1
workflows:
# the always-run workflow is always triggered, regardless of the pipeline parameters.
always-run:
jobs:
# the path-filtering/filter job determines which pipeline
# parameters to update.
- path-filtering/filter:
name: check-updated-files
# 3-column, whitespace-delimited mapping. One mapping per
# line:
# <regex path-to-test> <parameter-to-set> <value-of-pipeline-parameter>
mapping: |
service1/.* run-build-service-1-job true
service2/.* run-build-service-2-job true
base-revision: main
# this is the path of the configuration we should trigger once
# path filtering and pipeline parameter value updates are
# complete. In this case, we are using the parent dynamic
# configuration itself.
config-path: .circleci/continue_config.ymlcontinue_config.yml
version: 2.1
orbs:
maven: circleci/maven@1.2.0
# the default pipeline parameters, which will be updated according to
# the results of the path-filtering orb
parameters:
run-build-service-1-job:
type: boolean
default: false
run-build-service-2-job:
type: boolean
default: false
# here we specify our workflows, most of which are conditionally
# executed based upon pipeline parameter values. Each workflow calls a
# specific job defined above, in the jobs section.
workflows:
# when pipeline parameter, run-build-service-1-job is true, the
# build-service-1 job is triggered.
service-1:
when: << pipeline.parameters.run-build-service-1-job >>
jobs:
- maven/test:
name: build-service-1
command: 'install -DskipTests'
app_src_directory: 'service1'
# when pipeline parameter, run-build-service-2-job is true, the
# build-service-2 job is triggered.
service-2:
when: << pipeline.parameters.run-build-service-2-job >>
jobs:
- maven/test:
name: build-service-2
command: 'install -DskipTests'
app_src_directory: 'service2'
# when pipeline parameter, run-build-service-1-job OR
# run-build-service-2-job is true, run-integration-tests job is
# triggered. see:
# https://circleci.com/docs/configuration-reference/#logic-statements
# for more information.
run-integration-tests:
when:
or: [<< pipeline.parameters.run-build-service-1-job >>, << pipeline.parameters.run-build-service-2-job >>]
jobs:
- maven/test:
name: run-integration-tests
command: '-X verify'
app_src_directory: 'tests'上記の例では、以下のような要素が実装されています:
-
設定ファイルの最上部に
setup: trueという行を追加して、CircleCI のダイナミックコンフィグ機能を使用するように指定します。 -
path-filteringOrb とmavenOrb を呼び出して、使用できるようにします。 -
run-build-service-1-jobとrun-build-service-2-jobという 2 つのブール値パイプラインパラメーターを定義します。 -
check-updated-files、build-service-1、build-service-2、run-integration-testsという 4 つのジョブを定義します。-
check-updated-filesジョブ:path-filteringOrb を使用して、指定されたファイルパスのどのファイルに変更が加えられたのかを判断します。 また、指定されたパイプラインパラメーターに所定の値を設定します。 今回は、変更されたファイルに応じて各種 maven コマンドがトリガーされるようにしています。 -
build-service-1ジョブ:mavenOrb を使用して service1 コードのコンパイルとインストールを行います。 テストはスキップします。 -
build-service-2ジョブ:mavenOrb を使用して service2 コードのコンパイルとインストールを行います。 テストはスキップします。 -
run-integration-testsジョブ:mavenOrb を使用して結合テストを行います。
-
-
以下の 4 つのワークフローを定義します。 そのうち、3 つのワークフローは条件に従って実行されます。
-
service-1ワークフロー: run-build-service-1-job にマッピングされたパイプラインパラメータの値がtrueの場合にbuild-service-1ジョブをトリガーします。 -
service-2ワークフロー: run-build-service-2-job にマッピングされたパイプラインパラメータの値がtrueの場合にbuild-service-2ジョブをトリガーします。 -
run-integration-testsワークフロー: path-filtering` Orb の実行結果に基づいてrun-build-service-1-jobまたはrun-build-service-2-jobパイプラインパラメータの値がtrueに更新された場合に実行されます。 -
check-updated-filesワークフロー: このパイプラインがトリガーされた場合に必ず実行されます。
-
利用可能な要素と必須パラメーターの詳細については、path-filtering Orb のドキュメント を参照してください。