CircleCI 構成クックブック

CircleCI 構成クックブックは、CircleCI のリソース (CircleCI やパートナーの承認済み Orbs など) を使用してさまざまな構成タスクを行うための詳しい手順について、ユースケースごとにまとめた「レシピ集」です。 このクックブックと関連セクションを参照することで、CircleCI プラットフォームで繰り返し行われるタスクをすばやく簡単に実行できるようになります。

はじめに

#header4

This page, and its associated recipes, describes how you can perform specific configuration tasks. Recipes include code snippets and examples for you to customize to fit your projects. この「クックブック」の「レシピ」はそれぞれ 1 つのタスクに対応します。 これらのタスクは、CircleCI Orb などの CircleCI リソースに加えて、ユーザー独自のリソースを使用して CircleCI プラットフォームで実行できます。

CircleCI Orb とは

現在提供されている Orb の一覧は、CircleCI Orb レジストリにて確認してください。

CircleCI Orb は、CircleCI プラットフォームを効率的に使用するための構成パッケージです。 Orb を使用すると、複数のプロジェクトで構成を共有、標準化、簡略化することができます。 構成のベスト プラクティスの参考として Orb を使用することも可能です。

この Orb とその機能の詳細については、CircleCI Orb レジストリの Slack Orb を参照してください。

既存の Orb を 2.1 の .circleci/config.yml ファイルで使用するには、orbs キーを使用して呼び出します。 以下の例では、circleci 名前空間で hello-build Orb を呼び出します。

version: 2.1

orbs:
  hello: circleci/hello-build@0.0.5

workflows:
  "Hello Workflow":
    jobs:
      - hello/hello-build

For more detailed information about CircleCI orbs, refer to the Orbs Introduction page.

CircleCI プラットフォームおよび Orb を使用するための環境構成

3) 既存のワークフローやジョブで Orb エレメントを呼び出します (aws-ecs elements など)。

Most recipes in this cookbook call for version 2.1 configuration, pipelines and often, orbs. Before using the examples provided, you should check that you are set up for these features. The following notes and steps will get you where you need to be.

  • GCLOUD_SERVICE_KEY (必須)
  • We have indicated where you need to specify a docker image for your job with <docker-image-name-tag>.
  • If you wish to remain using version 2.0 config, or are using a self-hosted installation of CircleCI Server, these recipes are still relevant because you can view the expanded orb source within the Orbs Registry to see how the individual jobs and commands are built.
  • In the examples on this page that use orbs, you will notice that the orbs are versioned with tags, for example, aws-s3: circleci/aws-s3@x.y.z. If you copy paste any examples you will need to edit x.y.z to specify a version. You can find the available versions listed on the individual orb pages in the CircleCI Orbs Registry.
  • Any items that appear within < > should be replaced with your own parameters.

ソフトウェアの変更を Amazon ECS にデプロイする

Amazon Elastic Container Service (ECS) は、スケーラブルなコンテナ オーケストレーション サービスです。Docker コンテナをサポートし、コンテナ化されたアプリケーションを AWS で実行およびスケールできます。 Amazon ECS を使用することで、独自のコンテナ オーケストレーション ソフトウェアをインストール・構成せずに済むため、デプロイの複雑性を軽減し、CircleCI プラットフォームでコンテナをシンプルかつ最適にデプロイすることができます。 このセクションでは、CircleCI Orb を使用してソフトウェアの変更を Amazon ECS サービスにすばやく簡単にデプロイする方法を取り上げますが、Amazon ECS サービスの機能や基本的なコンポーネントとアーキテクチャについての詳細情報を確認したい場合は、Amazon ECS のドキュメントを参照してください。

構成レシピ

環境変数を設定する 以下の環境変数を CircleCI に直接またはコンテキスト経由で設定する必要があります。

  • AWS_ECR_ACCOUNT_URL
  • MY_APP_PREFIX
  • AWS_REGION
  • AWS_ACCESS_KEY_ID

上の例では、2 つの Orb (aws-cli: circleci/aws-cli@0.1.4aws-ecs: circleci/aws-ecs@0.0.3) をインスタンス化し、いくつかの連続したステップを実行して、Amazon CLI をインストール・構成してから、Amazon ECS サービスを更新しています。

メモ: If you do not already have Pipelines enabled, you will need to go to Project Settings > Advanced Settings and turn it on.

前提条件

CircleCI Amazon ECS/ECR Orb の詳細については、CircleCI Orb レジストリを参照してください。

CircleCI Orb を使用して、AWS CLI を更新せずに Amazon ECS サービスを更新するには、ECS サービスの更新方法を示す以下の例を参照してください。

aws-ecs: circleci/aws-ecs@0.0.10

Google Kubernetes Engine (GKE) にソフトウェアの変更をデプロイする前に以下の要件を満たしている必要があります。

Amazon ECS サービスを更新する

以下の環境変数を CircleCI に直接またはコンテキスト経由で設定する必要があります。

Amazon ECS サービスの更新を検証する To keep your config as simple as possible, use the AWS CLI and ECS orbs. This time, rather than using an orb’s built-in job to perform the required process, commands from the orbs are used as steps in the definition of the job named verify-deployment.

version: 2.1
orbs:
  aws-ecr: circleci/aws-ecr@0.0.4
  aws-ecs: circleci/aws-ecs@0.0.3
workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image:
          account-url: '${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com'
          repo: '${MY_APP_PREFIX}'
          region: '${AWS_REGION}'
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy-service-update:
          requires:
            - aws-ecr/build_and_push_image
          family: '${MY_APP_PREFIX}-service'
          cluster-name: '${MY_APP_PREFIX}-cluster'
          container-image-name-updates: 'container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}'

この例は、Orb を使用して AWS CLI をインストール・構成し、タスク定義を取得してから、このリビジョンがデプロイされたかどうかを検証する方法を示しています。 イメージを構成して Amazon ECS にプッシュする方法の詳細については、AWS ECR Orb のサンプルを参照してください。

Docker イメージを GKE クラスタにロールアウトしながら、これらのアクションを実行するコードの例を以下に示します。

ソフトウェアの変更を Google Kubernetes Engine (GKE) にデプロイする

gcloud のインストール (必要な場合) および初期化と、Docker イメージの更新を完了したら、この更新したイメージを後から使用できるように GKE クラスタにパブリッシュおよびロールアウトできます。

Google Kubernetes Engine (GKE) を利用すると、CI/CD 戦略を自動化して、コードやアプリケーションの更新を顧客にすばやく簡単にデプロイできます。 更新の配信に長い時間はかかりません。 CircleCI は、GKE 固有の CircleCI Orb を開発すると共に、GKE のテクノロジーを活用して、特定のジョブで GKE を操作できるようにしました。 GKE を使用する前に、Google Kubernetes Engine のドキュメントをご一読ください。

前提条件

CircleCI が開発した Kubernetes Orb は、Amazon Elastic Container Service (ECS) と組み合わせて以下のタスクに使用できます。 以下の環境変数を CircleCI に直接またはコンテキスト経由で設定する必要があります。

  • EKS クラスタの作成
  • GOOGLE_PROJECT_ID
  • GOOGLE_COMPUTE_ZONE

Amazon EKS サービスを使用する前に、以下の要件を満たしていることを確認してください。

GKE アクションを管理する

以下のステップを実行して、CircleCI と Orb を使用できるように環境を構成します。 Using the CircleCI GKE orb, you can perform complex actions with minimal configuration required. For example, once you have set the environment variable mentioned in the previous section, you can create a new GKE cluster using the following snippet:

version: 2.1
orbs:
  aws-cli: circleci/aws-cli@0.1.4
  aws-ecs: circleci/aws-ecs@0.0.3
jobs:
  update-tag:
    docker:
      - image: 'circleci/python:3.7.1'
    steps:
      - aws-cli/install
      - aws-cli/configure:
          aws-access-key-id: $AWS_ACCESS_KEY_ID
          aws-region: $AWS_REGION
      - aws-ecs/update-service:
          family: '${MY_APP_PREFIX}-service'
          cluster-name: '${MY_APP_PREFIX}-cluster'
          container-image-name-updates: 'container=${MY_APP_PREFIX}-service,tag=stable'
workflows:
  deploy:
    jobs:
      - update-tag

To delete a cluster, all you need is:

version: 2.1
orbs:
  aws-cli: circleci/aws-cli@0.1.4
  aws-ecs: circleci/aws-ecs@0.0.3
jobs:
  verify-deployment:
    docker:
      - image: 'circleci/python:3.7.1'
    steps:
      - aws-cli/install
      - aws-cli/configure:
          aws-access-key-id: $AWS_ACCESS_KEY_ID
          aws-region: $AWS_REGION
      - run:
          name: 最後のタスク定義の取得
          command: >
            TASK_DEFINITION_ARN=$(aws ecs describe-task-definition \
                --task-definition ${MY_APP_PREFIX}-service \
                --output text \
                --query 'taskDefinition.taskDefinitionArn')
            echo "export TASK_DEFINITION_ARN='${TASK_DEFINITION_ARN}'" >>
            $BASH_ENV
      - aws-ecs/verify-revision-is-deployed:
          family: '${MY_APP_PREFIX}-service'
          cluster-name: '${MY_APP_PREFIX}-cluster'
          task-definition-arn: '${TASK_DEFINITION_ARN}'
workflows:
  test-workflow:
    jobs:
      - verify-deployment

GKE クラスタにイメージをパブリッシュおよびロールアウトする

2) If you do not already have Pipelines enabled, you will need to go to Project Settings > Advanced Settings and turn it on.

CircleCI GKE Orb を使用して Google Cloud Platform (GCP) にログインし、Docker イメージをビルドおよびパブリッシュして、そのイメージを GKE クラスタにロールアウトする例を示します。 All you need is the orbs built-in command publish-and-rollout-image, along with definitions for a few required parameters. For a full list of of parameters available for this job, check the GKE page in the CircleCI Orbs Registry.

version: 2.1
commands:
  install:
    description: "`gcloud`  `kubectl` がまだインストールされていない場合はインストールします"
    steps:
      - gcloud/install
      - k8s/install
  init:
    description: "`gcloud` CLI を初期化します"
    steps:
      - gcloud/initialize
  rollout-image:
    description: "デプロイの Docker イメージを更新します"
    parameters:
      deployment:
        description: "Kubernetes デプロイ名"
        type: string
      container:
        description: "Kubernetes コンテナ名"
        type: string
      image:
        description: Docker イメージの名前
        type: string
    steps:
      - run: |
          gcloud container clusters get-credentials <<parameters.deployment>>
          kubectl set image deployment <<parameters.deployment>> <<parameters.container>>=<<parameters.image>>

Amazon Elastic Container Service for Kubernetes (Amazon EKS) を使用する

Amazon Elastic Container Service for Kubernetes (Amazon EKS) を使用する

3) 既存のワークフローやジョブで aws-eks エレメントを使用します。

  • EKS クラスタの作成
  • Kubernetes デプロイの作成
  • Helm Chart のインストール
  • コンテナ イメージの更新

まだ Amazon eksctl ツールがインストールされていない場合は、eksctl をインストールし、これらのツールを使用して EKS (Amazon EC2 用マネージド Kubernetes サービス) でクラスタを管理できるようにします。

EKS クラスタを作成する

CircleCI Orb を使用して環境に ‘eksctl’ ツールをインストールするコードの例を以下に示します。

Using the CircleCI aws-eks orb, you can create, test and teardown an EKS cluster using the code sample shown below.

orbs: aws-eks: circleci/aws-eks@0.2.1

In this example two orbs are used: built-in jobs and commands from the aws-eks orb are used to create, test and then teardown a cluster. The built-in install command from the kubernetes orb is used to install kubectl.

Kubernetes デプロイの作成

メモ: curl が有効で、amd64 アーキテクチャが使用されていることを確認してください。

CircleCI AWS-EKS Orb を使用するための要件を満たしていることが確認できたら、以下のコード例を使用して EKS クラスタを作成できます。

  • クラスタ内のリソースの更新
  • Authenticator を使用した Kubernetes 構成の更新
  • コンテナ イメージの更新

Kubernetes デプロイを作成するコードの例を示します。

version: 2.1
description: |
  EKS 上のリソースのコンテナ イメージを更新します
executor: << parameters.executor >>
parameters:
  aws-profile:
    default: ''
    description: |
      使用する AWS プロファイル。 指定されない場合は、AWS CLI インストールに
      構成されているデフォルトのプロファイルが使用されます。
    type: string
  aws-region:
    default: ''
    description: |
      この EKS クラスタが属する AWS リージョン
    type: string
  cluster-name:
    description: |
      EKS クラスタの名前
    type: string
  container-image-updates:
    description: |
      `kubectl set image` によってリソースに適用する
      コンテナ イメージの更新をリストします。
      形式は、CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N
      のようなスペース区切りの名前・値ペアです。
      例: "busybox=busybox nginx=nginx:1.9.1"
    type: string
  executor:
    default: python3
    description: |
      このジョブに使用する Executor
    type: executor
  get-rollout-status:
    default: false
    description: |
      ロールアウトのステータスを取得します。
      これは、`kubectl rollout` サブコマンドの使用が有効な
      リソース タイプにのみ使用できます。
    type: boolean
  namespace:
    default: ''
    description: |
      使用する Kubernetes の名前空間
    type: string
  pinned-revision-to-watch:
    default: ''
    description: |
      監視するリビジョンを固定します。

EKS クラスタを作成する

クラスタに Helm Chart をインストールする

Helm は、Kubernetes クラスタ上で実行される強力なアプリケーション パッケージ マネージャーです。Helm Chart を使用することで、アプリケーション構造を記述し、シンプルなコマンドによってその構造を管理できます。 Helm では、関連する Kubernetes リソース一式を記述するファイルが、チャートと呼ばれるパッケージ形式に集約されます。 1 つのチャートを使用して、memcached ポッドのような単純なアプリケーションから、HTTP サーバー、データベース、キャッシュなどから成る完全な Web アプリ スタックのような複雑なアプリケーションまで、幅広くデプロイできます。

Kubernetes クラスタに Helm をインストールしたら、以下のコード例を使用して Helm Chart をインストールできます。 Below is a code example for this, wchich also cleans up by deleting the release and cluster at the end of the process:

version: 2.1
description:
要件: curl、amd64 アーキテクチャ
steps:
  - run:
      command: >
        if which eksctl > /dev/null; then
          echo "eksctl is already installed"
          exit 0
        fi

        mkdir -p eksctl_download

        curl --silent --location --retry 5
        "https://github.com/weaveworks/eksctl/releases/download/latest_release/eksctl_$(uname
        -s)_amd64.tar.gz" \
          | tar xz -C eksctl_download
        chmod +x eksctl_download/eksctl

        SUDO=""

        if [ $(id -u) -ne 0 ] && which sudo > /dev/null ; then
          SUDO="sudo"
        fi

        $SUDO mv eksctl_download/eksctl /usr/local/bin/

        rmdir eksctl_download
      name: eksctl ツールのインストール

CircleCI ジョブでカスタム Slack 通知を利用する

CircleCI ジョブでカスタム Slack 通知を利用する

Slack は、リアルタイム コラボレーション アプリケーションです。チーム メンバーは、カスタムのチャンネルやワークスペースを通じて、定型業務やプロジェクトに協力して取り組むことができます。 CircleCI プラットフォームを使用するときには、チームのニーズと要件に基づいて Slack アプリのカスタム通知を有効にしておくと便利です。

Kubernetes デプロイを作成する

Slack チャンネルに承認待ちを通知する

CircleCI Slack Orb を使用すると、さまざまな通知やメッセージを作成して必要な受信者に配信できます。 その 1 つである「承認」通知を作成すると、承認が保留中であることを受信者に通知できるようになります。 CircleCI ジョブでこの承認通知を作成する例を以下に示します。

version: 2.1
orbs:
  slack: circleci/slack@1.0.0
version: 2.1
workflows:
  your-workflow:
    jobs:
      - slack/approval-notification:
          message: Pending approval
          webhook: webhook

上記のステップを実行してから、CircleCI Slack Orb (circleci/slack@1.0.0) を呼び出すと、ワークフローが開始されて通知が配信されます。

There are several parameters for you to customize your Slack notifications that aren’t shown here. For more detailed information about this orb and its functionality, refer to the Slack orb in the CircleCI Orb Registry.

クラスタに Helm をインストールする

カスタム メッセージを付けて Slack チャンネルに通知する

CircleCI Slack Orb では、カスタム メッセージを含む通知も作成できます。 この種類の通知は、ワークフロー、ジョブ、またはプロジェクトに固有の詳細なメッセージを受信者に配信したいときに便利です。

カスタム メッセージを作成して特定の Slack チャンネルでユーザーに配信する例を以下に示します。

version: 2.1
jobs:
  test-cluster:
    executor: aws-eks/python3
    parameters:
      cluster-name:
        description: |
          EKS クラスタの名前
        type: string
    steps:
      - kubernetes/install
      - aws-eks/update-kubeconfig-with-authenticator:
          cluster-name: << parameters.cluster-name >>
      - run:
          command: |
            kubectl get services
          name: クラスタのテスト
orbs:
aws-eks: circleci/aws-eks@0.1.0
kubernetes: circleci/kubernetes@0.3.0
version: 2.1
workflows:
deployment:
    jobs:
      - aws-eks/create-cluster:
          cluster-name: my-eks-demo
      - test-cluster:
          cluster-name: my-eks-demo
          requires:
            - aws-eks/create-cluster
      - aws-eks/delete-cluster:
          cluster-name: my-eks-demo
          requires:
            - test-cluster

CircleCI Heroku Orb の詳細については、CircleCI Orb レジストリを参照してください。

  1. メッセージ テキストの color を指定します。
  2. メッセージの受信者 (mentions) を指定します。
  3. 配信したいテキストを message に入力します。
  4. メッセージの webhook を指定します。Slack Web フックの作成方法については、こちらのガイドを参照してください。

コンテナ イメージを更新する

ジョブの終了時に成功または失敗のステータス アラートを送信する

ジョブの終了時に受信者にステータス アラートを送信することも可能です。 このステータス アラートの送信は、ジョブの最後のステップにする必要があります。

ジョブの終了時にステータス アラートを送信する例を以下に示します。

version: 2.1
jobs:
  create-deployment:
    executor: aws-eks/python3
    parameters:
      cluster-name:
        description: |
          EKS クラスタの名前
        type: string
    steps:
      - checkout
      - aws-eks/update-kubeconfig-with-authenticator:
          cluster-name: << parameters.cluster-name >>
          install-kubectl: true
      - kubernetes/create-or-update-resource:
          get-rollout-status: true
          resource-file-path: tests/nginx-deployment/deployment.yaml
          resource-name: deployment/nginx-deployment
orbs:
  aws-eks: circleci/aws-eks@0.1.0
  kubernetes: circleci/kubernetes@0.3.0
version: 2.1
workflows:
  deployment:
    jobs:
      - aws-eks/create-cluster:
          cluster-name: eks-demo-deployment
      - create-deployment:
          cluster-name: eks-demo-deployment
          requires:
            - aws-eks/create-cluster
      - aws-eks/update-container-image:
          cluster-name: eks-demo-deployment
          container-image-updates: 'nginx=nginx:1.9.1'
          post-steps:
            - kubernetes/delete-resource:
                resource-names: nginx-deployment
                resource-types: deployment
                wait: true
          record: true
          requires:
            - create-deployment
          resource-name: deployment/nginx-deployment
      - aws-eks/delete-cluster:
          cluster-name: eks-demo-deployment
          requires:
            - aws-eks/update-container-image

上の例では、ジョブが実行されて失敗した場合に、Slack ステータス アラートが受信者 (USERID1、USERID2) に送信されます。

この Orb とその機能の詳細については、CircleCI Orb レジストリの Slack Orb を参照してください。

Selecting a workflow to run using pipeline parameters

You might find that you want to be able to trigger a specific workflow to run, manually, using the API, but still run a workflow on every push to your project. To achieve this, use pipeline parameters to decide which workflow(s) to run.

Docker イメージをビルドしたら、以下のステップを実行してカスタム通知を作成します。

version: 2.1

parameters:
  action:
    type: enum
    enum: [build, report]
    default: build

jobs:
  build:
    machine: true
    steps:
      - checkout
      - run: ./run-tests.sh

  report:
    machine: true
    steps:
      - checkout
      - run: ./create-report.sh

workflows:
  build:
    when:
      equal: [ build, << pipeline.parameters.action >> ]
    jobs:
      - build

  report:
    when:
      equal: [ report, << pipeline.parameters.action >> ]
    jobs:
      - report

The action parameter will default to build on pushes to the project. Below is an example of supplying a different value to action using the API v2 Trigger a New Pipeline endpoint to select a different workflow to run, in this example, the workflow named report would run. Remember to substitute project-slug with your values.

curl -X POST https://circleci.com/api/v2/project/{project-slug}/pipeline \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Circle-Token: API_KEY' \
  -d '{ "parameters": { "action": report } }'

For more information on using API v2 endpoints, see the API Reference Documentation and the API Developers Guide Worked Example.

Branch-filtering for job steps

ジョブの終了時にステータス アラートを送信する例を以下に示します。

上の例では、ジョブが実行されて失敗した場合に、Slack ステータス アラートが受信者 (USERID1、USERID2) に送信されます。

The following example shows using the pipeline value pipeline.git.branch to control when a step should run. In this case the step run: echo "I am on master" only runs when the commit is on the master branch:

version: 2.1
jobs:
  publish-and-rollout-image:
    description: "新しい Docker イメージでクラスタを更新します"
    machine: true
    parameters:
      deployment:
        description: "Kubernetes デプロイ名"
        type: string
      container:
        description: "Kubernetes コンテナ名"
        type: string
      gcloud-service-key:
        description: gcloud サービス キー
        type: env_var_name
        default: GCLOUD_SERVICE_KEY
      google-project-id:
        description: gcloud CLI から接続する Google プロジェクト ID
        type: env_var_name
        default: GOOGLE_PROJECT_ID
      google-compute-zone:
        description: gcloud CLI から接続する Google コンピュート ゾーン
        type: env_var_name
        default: GOOGLE_COMPUTE_ZONE
      registry-url:
        description: ['', us, eu, asia].gcr.io からの GCR レジストリ URL
        type: string
        default: gcr.io
      image:
        description: Docker イメージの名前
        type: string
      tag:
        description: Docker イメージ タグ
        type: string
        default: "latest"
      path-to-dockerfile:
        description: イメージのビルド時に使用する Dockerfile の相対パス
        type: string
        default: "."

ダイナミック コンフィグ

このセクションは、「ダイナミック コンフィグ」を読み、「CircleCI のダイナミック コンフィグの使用を開始する」セクションに記載の手順を完了済みであることを前提としています。

ここでは、下記のダイナミック コンフィグの使用方法の例を紹介します。

基本的な例

以下に、CircleCI のダイナミック コンフィグ機能の基本的な使用例を示します。 この例では、generate-config スクリプトが既に存在することを前提としています。 このスクリプトは、行う処理の種類に基づいて新しい YAML 設定ファイルを出力します。 この過程で、git 履歴、パイプラインに渡される値、job 内で行われる処理などの検査を行うことができます。

version: 2.1

# CircleCI のダイナミック コンフィグ機能を有効にする。
setup: true 

# ダイナミック コンフィグの使用には continuation Orb が必要。
orbs:
  continuation: circleci/continuation@0.1.2

# ジョブとステップの定義
jobs:
  setup:
    executor: continuation/default
    steps:
      - checkout # コードのチェックアウト
      - run: # コマンドの実行
          name: 設定ファイルの生成
          command: |
            ./generate-config > generated_config.yml 
      - continuation/continue:
          configuration_path: generated_config.yml # 新しく生成した設定ファイルを使用して続行

# 上記で定義した setup ジョブをトリガーする 1 つのワークフロー。
workflows:
  setup:
    jobs:
      - setup

上記の設定ファイルは、以下のように構成されています。

  • 設定ファイルの最上部に setup: true という行を追加して、CircleCI のダイナミック コンフィグ機能を使用することを指定します。
  • ダイナミック コンフィグ機能を使用するために continuation Orb を呼び出します。
  • continuation Orb を executor として使用する setup というジョブを定義します。 このジョブでは、下記の処理を行います。
    • checkout ステップを呼び出して、設定されたリポジトリからコードをチェックアウトします。
    • run ステップを呼び出して、generate-config スクリプトを実行します。これで、continuation Orb の continue ジョブに出力を渡すことができます。
    • 必須の configuration_path に指定された設定ファイルに基づいて、パイプラインの実行が続行されます。
  • 最後に、workflows において、上記で定義された setup ジョブを呼び出します。

continuation Orb の処理について詳しくは、CircleCI デベロッパー ハブで Orb のソース コードを参照するか、「ダイナミック コンフィグに関するよくあるご質問」を参照してください。

変更されたファイルに基づいて特定のワークフローまたはステップを実行する

場合によっては、あるワークフローステップを実行するかどうかを、特定のファイルセットに対して行われた変更に応じて決定したいことがあります。 条件に応じた実行は、コードやマイクロサービスがモノレポ (単一のリポジトリ) に格納されている場合に役立ちます。

これを可能にするために、CircleCI には path-filtering Orb が用意されています。この Orb により、更新対象ファイルの具体的なパスに基づいて、パイプラインの実行を続行できます。

たとえば、以下のようなモノレポ構造を考えてみましょう。

.
├── .circleci
│   └── config.yml
├── service1
│   ├── Service1.java
├── service2
│   ├── Service2.java
├── tests
│   ├── IntegrationTests.java

上記を前提に CircleCI のダイナミック コンフィグを実装すると、config.yml は次のようになります。

version: 2.1

# CircleCI のダイナミック コンフィグ機能を有効にする
setup: true

# 更新対象ファイルセットのパスに基づいてパイプラインを続行するには path-filtering Orb が必要
# ダイナミック コンフィグを使用して Java プロジェクトをビルドする例として maven Orb も使用する。
orbs:
  path-filtering: circleci/path-filtering@0.0.2
  maven: circleci/maven@1.2.0

# デフォルトのパイプライン パラメーター。path-filtering Orb の結果に応じて更新される
parameters:
  run-build-service-1-job:
    type: boolean
    default: false
  run-build-service-2-job:
    type: boolean
    default: false

# ジョブの定義
jobs:
  # check-updated-files ジョブでは path-filtering Orb を使用して、更新するパイプライン パラメーターを判断する。
  check-updated-files:
    - path-filtering/filter:
        # 空白文字で区切った 3 列のマッピング。 1 行につき 1 つのマッピング: <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: master
        # パス フィルタリングとパイプライン パラメーターの値の更新が完了したらトリガーする構成ファイルのパス。 今回は、親ダイナミック コンフィグ自体を使用する。
        config-path: .circleci/config.yml
  # build-service-1 ジョブでは maven Orb を使用して service1 のアーティファクトを maven リポジトリにビルドしてインストールする (テストは実行しない)。
  build-service-1:
    - maven/test:
        command: ‘install -DskipTests’
        app_src_directory: ‘service1’
  # build-service-2 ジョブでは maven Orb を使用して service2 のアーティファクトを maven リポジトリにビルドしてインストールする (テストは実行しない)。
  build-service-2:
    - maven/test:
        command: ‘install -DskipTests’
        app_src_directory: ‘service2’
  # run-integration-tests ジョブでは tests ディレクトリで定義されたジョブを実行する。
  run-integration-tests:
    - maven/test:
        command: ‘-X verify’
        app_src_directory: ‘tests’

# 以下でワークフローを指定する。ワークフローの大半はパイプライン パラメーターの値に応じた条件に従って実行される。 
# 各ワークフローでは、上記の jobs セクションで定義された特定のジョブを呼び出す。
workflows:
  # パイプライン パラメーター run-build-service-1-job が true の場合、build-service-1 ジョブがトリガーされる。
  service-1:
    when: << pipeline.parameters.run-build-service-1-job >>
    jobs:
      - build-service-1
  # パイプライン パラメーター run-build-service-2-job が true の場合、build-service-2 ジョブがトリガーされる。
  service-2:
    when: << pipeline.parameters.run-build-service-2-job >>
    jobs:
      - build-service-2
  # パイプライン パラメーター run-build-service-1-job または run-build-service-2-job が true の場合、run-integration-tests ジョブがトリガーされる。
  # 詳細は https://circleci.com/docs/ja/2.0/configuration-reference/#logic-statements を参照。
  run-integration-tests:
    when: 
      or: [<< pipeline.parameters.run-build-service-1-job >>, << pipeline.parameters.run-build-service-2-job >>]
    jobs:
      - run-integration-tests
  # check-updated-files ジョブはパイプライン パラメーターの値にかかわらず必ずトリガーされる。
  always-run:
    jobs:
      - check-updated-files

上記の設定ファイルは、以下のように構成されています。

  • 設定ファイルの最上部に setup: true という行を追加して、CircleCI のダイナミック コンフィグ機能を使用することを指定します。
  • path-filtering Orb と maven Orb を呼び出して、使用できるようにします。
  • run-build-service-1-jobrun-build-service-2-job という 2 つのブール値パイプライン パラメーターを定義します。
  • check-updated-filesbuild-service-1build-service-2run-integration-tests という 4 つのジョブを定義します。
    • check-updated-files ジョブ: path-filtering Orb を使用して、指定されたファイルパスのどのファイルに変更が加えられたのかを判断します。 また、指定されたパイプライン パラメーターに所定の値を設定します。今回は、変更されたファイルに応じて各種 maven コマンドがトリガーされるようにしています。
    • build-service-1 ジョブ: maven Orb を使用して service1 コードのコンパイルとインストールを行います。テストはスキップします。
    • build-service-2 ジョブ: maven Orb を使用して service2 コードのコンパイルとインストールを行います。テストはスキップします。
    • run-integration-tests ジョブ: maven Orb を使用して結合テストを行います。
  • 以下の 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 のドキュメントを参照してください。

Use matrix jobs to run multiple OS tests

Using matrix jobs is a good way to run a job multiple times with different arguments, using parameters. There are many uses for this, including testing on multiple operating systems and against different language/library versions.

In the following example the test job is run across Linux, Windows and macOS environments, using two different versions of node. On each run of the test job different parameters are passed to set both the OS and the node version:

version: 2.1
jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - slack/notify:
          color: '#42e2f4'
          mentions: 'USERID1,USERID2,'
          message: This is a custom message notification
          webhook: webhook
orbs:
  slack: circleci/slack@1.0.0
version: 2.1
workflows:
  your-workflow:
    jobs:
      - build

The expanded version of this matrix runs the following list of jobs under the all-tests workflow:

    version: 2.1
jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - run: exit 0
      - slack/status:
          fail_only: 'true'
          mentions: 'USERID1,USERID2'
          only_for_branch: only_for_branch
          webhook: webhook
orbs:
  slack: circleci/slack@1.0.0
version: 2.1

For full details of the matrix jobs specification, see the Configuration Reference.



Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.