CircleCIで通知処理をカスタマイズする

はじめに

現在携わっているプロジェクトでは、1つのリポジトリで複数のモジュールのコードを管理しています(モノレポ構造)。
モジュールごとにlintや単体テストなどのジョブを実行しており、それぞれのジョブが成否を通知する設定となっていたため、大量の通知でチャットツールのタイムラインがすぐに流れてしまうことに悩まされていました。

そこで、ジョブが失敗した時、もしくは全ジョブが成功したのみ通知する形にしようとしたのですが、通常の設定だけでは対応することが出来ませんでした。
Orb(拡張機能のようなもの)を使うと、Slack向けの通知をカスタマイズすることは出来るようなのですが、現在使用しているチャットには対応していないため、コマンドを定義して自ら処理を作成しました。
(作成にあたっては、Slack用Orbのソースコードを大いに参考にさせていただきました )

この設定は、コマンド定義が利用可能なCircleCI・バージョン2.1が必要です。

手順

ステップ1: コマンドを定義する

通知を行う処理を、コマンドとして定義します。ここでは、シェルがbashの場合の例を挙げています。

最初の2つのステップ(steps)はジョブの成否で、どちらか一方の処理が実行されます。ジョブ成功ならばSuccess、失敗ならばFailureが、環境変数CI_JOB_STATUSに格納されます。
最後の3つ目のステップ(成否に関わらず実行される)では、前処理で格納されたCI_JOB_STATUSを参照して、通知の要否を判断しています。

この例では省略していますが、# ここで通知を実施とコメントが書かれている箇所で、通知用APIを呼び出すなど、実際の通知処理を行います。
通知に必要な情報は、環境変数で取得することができます。詳細はリファレンスを参照してください。

commands:
  notify-result:
    description: ジョブの処理結果通知処理
    parameters:
      event:
        description: |
          通知条件("Always": 常に通知, "Success": 成功時のみ, "Failure": 失敗時のみ)
        enum:
          - Always
          - Success
          - Failure
        type: enum
    steps:
      - run:
          name: ジョブのステータス検知(失敗)
          command: |
            echo 'export CI_JOB_STATUS="Failure"' >> $BASH_ENV
          when: on_fail
      - run:
          name: ジョブのステータス検知(成功)
          command: |
            echo 'export CI_JOB_STATUS="Success"' >> $BASH_ENV
          when: on_success
      - run:
          name: 通知処理の呼び出し
          command: |
            if [ "${CI_JOB_STATUS}" = "${NOTIFY_PARAM_EVENT}" ] || [ "${NOTIFY_PARAM_EVENT}" = "Always" ]; then
              source $BASH_ENV
              # ここで通知を実施
            else
              echo "Notification skipped."
              echo "Job status: ${CI_JOB_STATUS}, Parameters(event: ${NOTIFY_PARAM_EVENT})"
              exit 0
            fi
          environment:
            NOTIFY_PARAM_EVENT: <<parameters.event>>
          when: always

ステップ2: ジョブを定義する

ステップ1で作成したコマンドをジョブに組み込みます。
以下の例では、lintでエラーが検出されると通知が行われます。

jobs:
  exec-lint:
    description: lintの実行
    executor: sample-executor
    steps:
      - run:
          name: lintコマンドの実行
          command: yarn lint
      - notify-result:
          event: Failure

ステップ3: ワークフローに組み込む

作成したジョブをワークフローに組み込みます。
以下の例では、nameを指定してジョブに別名を付けています。

workflows:
  version: 2
  workflow-sample:
    jobs:
      - build
      - exec-lint:
          name: lint-backend
          requires:
            - build
      - exec-ut:
          name: ut-backend
          requires:
            - lint-backend

おまけ

設定ファイルのバリデーション

CircleCIのCLIをインストールしていると、設定ファイルのバリデーションが出来ます。
macOS で Homebrewが使用可能な環境であれば、以下のコマンドでCLIをインストール出来ます。

brew install circleci

リポジトリのルートディレクトリ(.circleciディレクトリが置いてある場所)にて、コマンドを実行します。結果が正常であれば、以下のように出力されます。

$ circleci config validate
Config file at .circleci/config.yml is valid.