Skip to Content

Slackアクション

Slackアクションは、Slackのチャンネルにメッセージを投稿します。投稿するのは、実行のノート、ワークフローに書いたテキスト、またはその両方です。

アクションは、ステップが通ったかどうかとは別に、人に向けたノートを残せます。後続のステップはそれをnotesとして読み、各ノートにはジョブとステップが付き、シークレットは隠されています。Probeはノートをどこにも投稿しません。このアクションはノートをSlackに投稿するので、criticalのノートや定期実行の失敗を、チームが普段やりとりしている場所で知らせられます。Slackに対して行うのはメッセージの投稿だけです。

外部アクションとしてmozership/probe-slack で公開しています。ワークフローが初めて使うときにProbeがダウンロードし、固定したコミットのaction.ymlが示すSHA-256と一致する実行ファイルだけを実行します。notesコンテキストを持つ最初のバージョンであるProbe v1.32.0以降が必要です。例の<commit SHA>には、固定するコミットを書きます。最新リリースのusesの行はprobe guide slackが表示し、各リリースのノートにもあります。

基本的な構文

ステップでは40文字のコミットSHAでアクションを固定します。各リリース のノートの先頭に、コピーして使うusesの行があります。このステップは最後のジョブに置き、そのジョブはalways付きでほかのジョブをneedsにします。こうすると、ほかのジョブがどう終わっても、すべて終わったあとに実行され、すべてのノートを読めます。

name: Nightly actions: slack: github.com/mozership/probe-slack@<commit SHA> secrets: - SLACK_WEBHOOK_URL vars: slack_webhook: "{{SLACK_WEBHOOK_URL}}" jobs: # helloは受け取ったwithをそのままresとして返すので、 # ノートを残すアクションの代わりに使える - name: Checkout id: checkout steps: - name: A first-time shopper uses: hello with: notes: - level: critical title: The checkout button is under the cookie banner body: On a 390px wide screen the banner covers the button until it is closed. - level: info body: The search took 4s to show results. - name: Tell the team needs: [checkout] always: true steps: - name: Post the critical notes uses: slack with: webhook_url: "{{vars.slack_webhook}}" text: Critical notes of the nightly run notes: "{{ filter(notes, .level == 'critical') }}" test: status == 0

2つの投稿方法

webhook_urltokenとchannel
仕組みIncoming Webhook chat:writeを持つボットトークンでchat.postMessageを呼ぶ
投稿先のチャンネルWebhookを作ったときのチャンネルボットが招待されたチャンネルのうち、channelにIDか#nameで指定したもの
返す値res.postedres.postedと、メッセージのres.channel、res.ts

Webhookはほかに何も要らないので、1つのチャンネルに投稿するならこちらです。トークンを使うと、ステップごとに指定したチャンネルに投稿できます。どちらか一方だけを指定し、WebhookのURLかトークンをsecretsに入れてください。WebhookのURLを知っていれば、誰でもそのWebhookに投稿できます。

- name: The critical notes, to the channel of the team on call uses: slack with: token: "{{vars.slack_token}}" channel: "#oncall" notes: "{{ filter(notes, .level == 'critical') }}"

実行のたびに新しいメッセージを投稿します。メッセージの編集やスレッドへの返信はしません。pushのたびに最新に保つメッセージは、github-notesでプルリクエストに投稿してください。

パラメータ

パラメータ型必須デフォルト説明
webhook_urlString2つの方法のどちらか-Incoming WebhookのURL
tokenString2つの方法のどちらか-chat:writeを持つボットトークン
channelStringtokenのとき-C0123456789のようなIDか、#nameで指定するチャンネル
textStringtextかnotes-ノートの上に書くMarkdown。単独でも投稿できる
notesArraytextかnotes-"{{ notes }}"のような、notesコンテキストのエントリ
api_urlStringいいえhttps://slack.com/apitokenで使うWeb API
timeoutDurationいいえ30sステップの制限時間。10sのような形式か秒数で指定する

どれにも当てはまらないキーは、ステップを失敗させます。action.ymlがこれらをparamsとして宣言しているので、probe checkはそのようなキーを行番号付きで報告します。

notesが空でtextもないときは、何も投稿せず、res.postedはfalseになります。ノートがなかったことを毎晩伝えるメッセージは、読む人にとって邪魔になるだけだからです。ノートがなくてもtextがあれば、それだけを投稿します。定期実行が失敗したことを伝えるときなどに使います。

notesは、notesコンテキストと同じ形のエントリを受け取ります。levelがinfo、warning、criticalのいずれでもないエントリや、bodyのないエントリがあると、ステップは失敗します。手で書いたリストではなく、コンテキストそのもの、またはfilter(notes, .level == 'critical')のようにその一部を渡してください。

投稿する内容

メッセージはBlock Kitのmarkdownブロックで組み立てるので、ノートのMarkdownは書いたとおりに表示されます。先頭にtext、次にレベルごとのノートの件数を数える1行、そのあとにノートごとのブロックが続きます。各ブロックには、レベルの絵文字、タイトル、本文と、ジョブ、ステップ、ステップの状態、repeatのジョブであれば何回目の実行かを示す1行が入ります。上のワークフローは次のメッセージを投稿します。

Critical notes of the nightly run **The run left 1 note: 1 critical.** 🚨 **critical · The checkout button is under the cookie banner** On a 390px wide screen the banner covers the button until it is closed. _Checkout › A first-time shopper · passed_

メッセージのプレーンテキストにも同じ内容が入ります。text、件数の1行、表示した各ノートのレベル、タイトル、ジョブ、ステップ、本文です。Slackはこれを通知に表示し、スクリーンリーダーはブロックの代わりにこれを読み上げます。

Probeが隠した値は、ノートの中では<secret:NAME>や<redacted>になっています。Slackはこれをリンクやメンションとみなすので、アクションはこれをコードとして書きます。コードの中では、そのまま表示されます。

Slackが受け付けるのは、1つのメッセージにつき50ブロックまでで、markdownブロックの合計は12000文字までです。これより長いメッセージでは末尾のノートを省き、省いた件数をブロックで書きます。ノートをすべて省いても収まらないほどtextが長いときは、ステップは失敗します。

レスポンスオブジェクト

プロパティ型説明
res.postedBooleanメッセージを投稿したかどうか
res.channelStringtokenのとき、メッセージのチャンネル。Webhookでは空
res.tsStringtokenのとき、Web APIでメッセージを指すタイムスタンプ。Webhookでは空
res.codeIntegerレスポンスのステータスコード。何も投稿しなかったときは0
reqObjectvia(webhookかtoken)、トークンのときはchannelとapi_url、text、notesの件数。WebhookのURLとトークンは含まない
rtDurationステップにかかった時間
statusInteger0

Slackがエラーを返すと、ステップはSlackの応答で失敗します。たとえばchat.postMessageのchannel_not_foundやnot_in_channel、削除されたWebhookの404 no_service、待つべき秒数付きの429です。投稿をSlackが301や302でリダイレクトした場合も失敗します。そのまま従うと、投稿がGETとして送り直されるためです。エラーにはWebhookのURLも、リダイレクト先のパスも含めず、ホストだけを書きます。

アクションは、投稿したノートをres.notesとして返しません。返すと、後続のステップに同じノートがもう一度残るためです。

ガードの下での動作

このアクションは実行のガードに従い、action.ymlでguard: [read-only, allow-host]を宣言しています。そのため、どちらのガードの下でも--allow-actionなしで実行します。拒否したステップは、リクエストを送る前に種類refusedで失敗します。

  • --read-onlyの下では、投稿は書き込みなので、すべてのステップを拒否します。
  • --allow-hostの下では、webhook_urlかapi_urlのホストと、各リダイレクト先のホストが、実行が許可するものでなければなりません。Webhookであればhooks.slack.com、トークンであればslack.comです。ポートのないURLは、スキームの既定のポートとして扱います。

ガードを参照してください。

関連項目

  • ノート - アクションがノートを残し、後続のステップがそれを読む仕組み
  • GitHub Notes - ノートをプルリクエスト、ジョブのサマリー、Issueに投稿する
  • 外部アクション - Probeが外部アクションを解決し、照合する仕組み
更新日時