本番環境へのデプロイ前に人間の判断を挟む場合、CircleCI では type: approval を使ってワークフローを一時停止させます。承認ジョブに到達したワークフローは on_hold 状態で待機し、誰かが承認するまで後続のジョブは実行されません。
type: approvalの使い方については、以下の記事で紹介していますので、こちらもご覧ください。
承認ゲートを置いたあとに運用で問題になるのは、停止したことの検知です。CircleCI には承認待ちを知らせる通知は、 Slack integration とメール通知の 2 つが用意されています。
本記事では、この 2 つを有効化して承認待ちを Slack とメールで受け取る手順を紹介します。どちらの方法も設定は Web UI 側で完結しますので、config.yml の変更は不要です。
承認待ちを知らせる 2 つの経路
承認待ち状態を通知する仕組みは、ユーザー単位とプロジェクト単位の２つで設定できます。プロジェクト単位の設定はチーム全体の共有に向いており、対象プロジェクトのワークフローが承認待ちになると、指定した Slack チャンネルに通知が届きます。もう一方のユーザー単位の設定では、自分がフォローしているプロジェクトの承認待ちだけがメールで届くため、担当プロジェクトを個人宛てに絞り込めます。
| 経路 | 設定場所 | 通知先 | スコープ |
|---|---|---|---|
| プロジェクト単位 | Project Settings > Slack Notifications | 指定した Slack チャンネル | 対象プロジェクトのすべてのワークフロー |
| ユーザー単位（メール） | User Settings > Notifications の Email タブ |
自分のメールアドレス | 自分がフォローしているプロジェクト |
プロジェクト単位で Slack チャンネルに通知する
Project Settings のサイドバーから Slack Notifications を選択します。Slack channel が未接続の場合、Add Slack channel ボタンだけが表示された状態になります。
通知イベントを選択する Events セクションは、Slack channel を接続したあとに表示されます。通知イベントはチャンネルごとの設定として扱われるため、接続先が決まっていない状態では設定対象そのものが存在しません。まず Add Slack channel から通知先のチャンネルを接続してください。
チャンネルを接続すると Events セクションが現れます。
Build カテゴリには 2 つのグループがあります。Workflow Completed はワークフローの完了イベントで、既定で On default branch (failed, error, unauthorized) が有効になっています。一方の Job はジョブ単位のイベントで、こちらは既定ですべて無効です。承認待ちはワークフロー単位ではなくジョブ単位のイベントとして分類されているため、Workflow Completed を有効にしているだけでは通知は届きません。
Job グループの下にある Job awaiting approval を有効化してください。有効化するとカテゴリ名の下に有効なイベントが列挙されるため、意図した組み合わせになっているかを画面上で確認できます。
プライベートチャンネルを通知先にする場合は、事前に CircleCI の bot をチャンネルに招待してください。
届く Slack 通知の内容
ワークフローが承認待ちで停止すると、指定したチャンネルに通知が届きます。
通知に含まれる情報は 3 種類です。
-
ワークフローの識別情報: 見出しに
On hold: <プロジェクト名> / <ワークフロー名>が表示され、その下に組織名、プロジェクト名、UTC のタイムスタンプ、ブランチ名、パイプライン番号が並びます。複数のプロジェクトを同じチャンネルに流していても、どのワークフローが停止したのかを通知だけで特定できます。 - トリガー元とコミット情報: ワークフローをトリガーしたユーザー名と、コミットの SHA、コミットメッセージ、コミットの author が含まれます。承認の判断に必要な変更内容を、CircleCI の Web UI を開く前に把握できます。
-
承認対象のジョブ名と操作リンク:
Job awaiting approvalという見出しの下に、承認待ちのジョブ名とApproveリンクが配置されます。このApproveは Slack 上で承認を確定するものではなく、CircleCI の Web UI のワークフロー画面へのリンクです。承認の確定は Web UI 側で行います。
自分がフォローしているプロジェクトをメールで受け取る
メール通知はユーザー単位の設定です。画面右上のアバターから User Settings を開き、サイドバーの Notifications を選択します。Categories セクションに Email タブと Slack タブがあるため、Email タブを選択してください。
Followed projects カテゴリを展開し、Job グループの下にある Awaiting approval を有効化します。
同じ画面には My work カテゴリもあります。こちらは自分がトリガーしたワークフローを対象とするカテゴリです。他のメンバーや Webhook がトリガーしたワークフローの承認待ちを受け取りたい場合は、My work ではなく Followed projects を有効化してください。承認は多くの場合、変更を加えた本人以外が行うため、承認する側が使うのは Followed projects になります。
承認待ちのメールが届かない場合、まず対象プロジェクトをフォローしているかを確認してください。Followed projects はフォロー中のプロジェクトのみを対象とするため、フォローしていないプロジェクトの通知は届きません。
あわせて、Build notification preferences で対象組織のメールアドレスが Don't send email notifications になっていないかも確認してください。
届くメールの内容
有効化したあとにワークフローが承認待ちで停止すると、設定したメールアドレスに通知が届きます。
差出人は CircleCI Builds <no-reply@builds.circleci.com>、件名は [CircleCI] On hold: <組織名> / <プロジェクト名> on <ブランチ名> の形式です。本文にはワークフローの識別情報、トリガー元、コミット情報が含まれ、Job awaiting approval という見出しの下に承認待ちのジョブ名と Approve ボタンが配置されます。Slack 通知と同じ情報が揃っているため、どちらの経路でも承認の判断ができます。Approve ボタンの挙動も Slack 通知と同じで、Web UI のワークフロー画面へ遷移します。
通知から承認するまでの流れ
Slack 通知の Approve リンク、メール通知の Approve ボタンは、いずれもその場で承認を確定するものではありません。公式ドキュメントにも、承認ジョブの通知にはワークフローへのリンクが含まれ、リンクを選択してワークフローを開き、そこで承認またはキャンセルを行うと記載されています。
Web UI で承認待ちのジョブを選択すると、Approval Job モーダルが開きます。モーダルには対象のワークフロー名と承認待ちのジョブ名が示され、Approve job と Cancel job を選択できます。
Approve job を選択すると、承認ジョブが完了して後続のジョブが実行されます。
この流れは Slack 通知でもメール通知でも同じです。通知が担うのは、承認待ちの発生を検知して該当する承認画面まで到達させるところまでで、承認の確定は Web UI 側に残ります。
まとめ
type: approval による承認ゲートは、本番デプロイ前に人間の判断を挟む仕組みとして機能します。一方で、承認待ちで停止したことに気づく経路は既定で無効になっているため、明示的に有効化する必要があります。Project Settings > Slack Notifications で Job awaiting approval を有効化すればチーム共有のチャンネルに通知が届き、User Settings > Notifications の Email タブで Followed projects の Awaiting approval を有効化すれば、フォロー中プロジェクトの承認待ちがメールで届きます。
今回は承認待ちのイベントを対象にしましたが、同じ Events セクションからワークフローの完了イベントやデプロイ関連のイベントも設定できます。より詳しく確認する場合は、Slack integration と Notifications を参照してください。通知イベントとして追加してほしいものがある場合は、CircleCI Ideas board から要望を投稿できます。