Slack Orb を使用した Slack の通知設定

5 months ago2 min read

クラウド

Server v4.x

Server v3.x

Server v2.x

このページの内容

アプリケーションを認証する

このガイドでは、CircleCI Slack Orb について説明します。

はじめに

Orb は、再利用が可能な設定要素をまとめた共有可能なオープンソースパッケージです。 Orb を使うと、設定が簡単になり、サードパーティアプリとの連携がサポートされ、時間を節約することができます。

CircleCI で最も広く利用されている Orb は Slack Orb です。 Slack Orb は、すべての CI/CD パイプラインにイベントベースの通知を実装できます。ビルトインのメッセージテンプレート、またはブラウザ上で表示確認ができる Slack の Block Kit Builder を使って、組織のニーズに合わせて通知を作成およびカスタマイズすることができます。

このチュートリアルでは、以下について説明します。

Slack Orb を使って config.yml ファイルを作成する方法
Slack の認証情報をコンテキストに保存する方法
テンプレートを使って成功および失敗したビルドのアラートを作成する方法
特定のチャンネル、チーム、人々にアラートを送信する方法
Slack Block Kit Builder を利用して独自のカスタムアラートを作成する方法

このチュートリアルに沿って実行するには、以下を準備する必要があります。

CircleCI のアカウント: アカウントをお持ちでない場合は、無料で登録していただけます。
GitHub や Bitbucket などのバージョン管理システム (VCS)
Slack のワークスペース（会社のワークスペースを使用したくない場合は、テスト用にご自身のワークスペースを作成することも可能です。）

ステップ 1: config.yml ファイルを作成する

まだ作成していない場合は、リポジトリのルートに .circleci フォルダを作成します。この .circleci フォルダーに config.yml ファイルを作成します。

下記のサンプルコードを config.yml にコピー & ペーストします。

version: 2.1
orbs:
  slack: circleci/slack@4.9.3
jobs:
  notify:
    docker:
      - image: 'cimg/base:stable'
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - slack/notify:
          custom: |
            {
              "blocks": [
                {
                  "type": "section",
                  "fields": [
                    {
                      "type": "plain_text",
                      "text": "*This is a text notification*",
                      "emoji": true
                    }
                  ]
                }
              ]
            }
          event: always
workflows:
  send-notification:
    jobs:
      - notify:
          context: slack-secrets

このサンプルコードの主な要素について説明します。

1 行目: ご使用の設定ファイルのバージョンです。 2.1 が最新のバージョンです。
2-3 行目: Orb スタンザです。使用しているのは slack: circleci/slack@4.9.3 Orb です。
5-7 行目: notify というジョブです。基本的な Docker コンテナで実行されます。
8-9 行目: slack/notify という Slack Orb と連動するためのステップです。
10-24 行目: このカスタムブロックには Slack Block Kit Builder からの基本的な通知が含まれます。お分かりのように、JSON 形式です。ステップ 3 では、より高度なテンプレートを使用します。
25 行目: event: always パラメーターは、この通知が すべて のイベントタイプにトリガーされていることを意味します。ステップ 3 では、各イベント毎に異なる通知を使用します。
30 行目: ここでは、Slack の認証情報をステップ 2 で保存する CircleCI コンテキストを参照します。

config.yml 基本ファイルの設定が完了しました。CircleCI と Slack を接続できます。

この時点でお客様の config.yml をコミットし、パイプラインをトリガーすると、ビルドが失敗します。これは次のステップで Slack 認証情報を追加する必要があるためです。

ステップ 2: CircleCI と Slack を接続する

ここでは以下の手順を行います。

Slack から API トークンを取得する
コンテキストを作成し、CircleCI に認証情報を保存する
通知を受け取るようパイプラインをトリガーする

アプリケーションを認証する

Slack Orb は、CircleCI 上でジョブの一部として実行するアプリケーションです。通知を受け取る前に、アプリケーションを認証する必要があります。

Slack アプリを作成する

Slack API ウェブサイトの Your Apps に行き、緑色の Create an App をクリックします。
From scratch を選択します。
アプリに、CircleCI などの名前をつけて、アプリを使用する Slack ワークスペースを選択します。このワークスペースは、後で変更することはできません。
緑色の Create App ボタンをクリックします。

アプリの権限を設定する

Basic Information のページで、Add features and functionality の下にある Permissions を探します。
OAuth & Permissions のページで、Scopes までスクロールダウンします。ここで Slack アプリの権限を作成します。
Bot Token Scopes の下にある Add an OAuth Scope をクリックします。
Slack Orb には、チャットメッセージを投稿する権限やファイルをアップロードする権限が必要なため、以下のスコープを作成します。
- chat:write
- chat:write.public
- files:write

Slack の通知をプライベートチェンネルで受け取るには、そのチャンネルに Slack アプリを追加する必要があります。チャンネルを開き、上部右端にあるチャンネルメンバーの写真をクリックし、Integrations タブをクリックします。ここから、アプリが追加できます。

アプリをインストールする

スコープを作成したら、ページの一番上に移動し、Install to Workspace ボタンをクリックします。
アプリに Slack ワークスペースにアクセスする権限を付与するか尋ねられます。
三角ボタンをクリックして権限を再確認し、緑色の Allow ボタンをクリックします。
Bot User OAuth Token が表示されます。このトークンをクリップボードにコピーし、CircleCI に追加できるようにしておきます。トークンを公開してしまわないよう、注意してください。

コンテキストを作成する

CircleCI では、コンテキストを使用すると、環境変数を保護しプロジェクト間で共有することができます。 Slack の認証情報を使ってコンテキストを作成すると、お客様とチームはそれを再利用することができます。

CircleCI の設定:

Organization Settings のページをクリックします。
コンテキストの下にある Create Context ボタンをクリックし、slack-secrets などの一意の名前を追加します（上記の config.yml ファイルで指定した名前です）。
青色の Create Context ボタンをクリックします。
今作成したコンテキスト名をクリックします。
青色の Add Environment Variable ボタンをクリックし、最初のキーと値のペアを入力します。
- Environment Variable Name は、SLACK_ACCESS_TOKEN です。
- 値は、Slack Bot User OAuth Access Token です。
Add Environment Variable ボタンをクリックして保存します。
Add Environment Variable ボタンをもう一度クリックします。
- Environment Variable Name は、SLACK_DEFAULT_CHANNEL です。
- 値は、通知を投稿するためのデフォルトの Slack チャンネルの ID です。この設定は個々のジョブにオーバーライドできます。

Slack チャンネルの ID を取得するには、Slack でそのチャンネルを右クリックし、Copy Link を選択します。 ID は URL の最後に表示され、 C034R26AM36 のような形式になります。

slack-secrets コンテキストが notify ジョブに含まれており、作成したものと名前が一致していることを確認します。

workflows:
  send-notification:
    jobs:
      - notify:
          context: slack-secrets

このコンテキストを他のジョブやプロジェクトで再利用できるようになりました。

config.yml ファイルをコミット (リモートで作業している場合は、コミット後にプッシュ) します。

アラートをトリガーする

CircleCI ダッシュボードでは、

Projects をクリックします。
リポジトリを見つけ、その隣にある青色の Set Up Project ボタンをクリックします。
config.yml ファイルをコミットしたブランチを選びます。
Set Up Project ボタンをクリックします。

これにより、お客様の認証情報を付加した Slack Orb を含む CircleCI パイプラインがトリガーされます。

すると緑色の Success バッジが表示され、notify ジョブの隣に緑色のチェックマークが表示されます。

お客様のジョブの上でクリックし、何が起きたのかを確認します。 Slack に送信されたメッセージの本文が表示されます。

ここで Slack ワークスペースを開きます。先程指定したデフォルトのチャンネルに、CircleCI パイプラインがトリガーしたアラートが表示されているはずです。

これは基本的なアラートですが、既に多くのことを達成しました。

Slack Orb を使って .circleci/config.yml ファイルを作成しました
Slack に関連付けられている環境変数を保存するコンテキストを作成しました
Slack アプリを作成しました

ステップ 3: メッセージテンプレートを使用する

Slack Orb には、様々な CircleCI イベントのチャンネル通知に使用できるたくさんの通知テンプレートが含まれています。

basic_success_1: ジョブが成功した pass イベント用
basic_fail_1: ジョブが失敗した fail イベント用
success_tagged_deploy_1: 成功したデプロイ用
basic_on_hold_1: 承認待ちの待機ジョブ用

ジョブでこれらのテンプレートを使用するには、event パラメーターと template パラメーターを config.yml ファイルの steps の下に含めます。例えば下記のようにします。

jobs:
  notify:
    docker:
      - image: 'cimg/base:stable'
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
- slack/notify:
	  event: fail
	  template: basic_fail_1
- slack/notify:
	  event: pass
	  template: success_tagged_deploy_1

7 行目 では、次の行のテンプレートが失敗したイベントに使われるよう指定します。
8 行目 では、使用するテンプレート、ここでは basic_fail_1 を指定します。
9 行目 では、次の行のテンプレートが成功したイベントに使われるよう指定します。
10 行目 では、使用するテンプレート、ここでは basic_success_1 を指定します。

ステップ 1 では汎用アラートを使用しましたが、ジョブが成功したか失敗したかに応じて異なるステップが追加されました。 Slack Orb により、適切なステップがトリガーされます。

更新した config.yml ファイルをコミット (リモートで作業している場合は、コミット後にプッシュ) します。パイプラインが完了すると、Slack チャンネルにより詳細なアラートが表示されます。

追加パラメーターを含める

失敗したジョブについて、メンションすることで特定の人やチームに知らせることができます。

- slack/notify:
	event: fail
	mentions: '@EngineeringTeam'
	template: basic_fail_1

複数のチャンネルに通知するには、ID を引用符で囲み、カンマで区切ります。

- slack/notify:
    channel: 'ABCXYZ, ZXCBN'
    event: fail
    template: basic_fail_1

アラートを特定のブランチに制限するには、branch_pattern パラメーターを追加します。

 - slack/notify:
      branch_pattern: main
      event: fail
      template: basic_fail_1

これは、フィーチャーブランチのアラートを受信しない場合に便利です。

Slack Block Kit Builder の使用

通知を更にカスタマイズするには、 Slack Block Kit Builder を使用します。このフレームワークを使用すると、イメージ、フォームフィールド、およびその他の対話型の要素を使用して、高度な通知を作成できます。

ブロック (JSON オブジェクト) を作成したら、custum パラメーター内の config.yml ファイルにコピー & ペーストします。

- slack/notify:
    event: always
    custom: | # your custom notification goes here
      {
        "blocks": [
          {
            "type": "section",
            "fields": [
              {
                "type": "plain_text",
                "text": "*This is a text notification*",
                "emoji": true
              }
            ]
          }
        ]
      }

まとめ

このチュートリアルでは、CircleCI の通知を Slack のチャンネルに送信できるように Slack Orb を設定しました。基本的な通知を作成し、Slack アプリを作成・認証し、テンプレートを使用しました。

その他の設定オプションについては、 Slack Orb のドキュメントを参照してください。また、 Orb レジストリでもその他のたくさんの Orb を参照していただけます。

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。ご協力いただき、ありがとうございます。

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.