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 == 02つの投稿方法
webhook_url | tokenとchannel | |
|---|---|---|
| 仕組み | Incoming Webhook | chat:writeを持つボットトークンでchat.postMessageを呼ぶ |
| 投稿先のチャンネル | Webhookを作ったときのチャンネル | ボットが招待されたチャンネルのうち、channelにIDか#nameで指定したもの |
| 返す値 | res.posted | res.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_url | String | 2つの方法のどちらか | - | Incoming WebhookのURL |
token | String | 2つの方法のどちらか | - | chat:writeを持つボットトークン |
channel | String | tokenのとき | - | C0123456789のようなIDか、#nameで指定するチャンネル |
text | String | textかnotes | - | ノートの上に書くMarkdown。単独でも投稿できる |
notes | Array | textかnotes | - | "{{ notes }}"のような、notesコンテキストのエントリ |
api_url | String | いいえ | https://slack.com/api | tokenで使うWeb API |
timeout | Duration | いいえ | 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.posted | Boolean | メッセージを投稿したかどうか |
res.channel | String | tokenのとき、メッセージのチャンネル。Webhookでは空 |
res.ts | String | tokenのとき、Web APIでメッセージを指すタイムスタンプ。Webhookでは空 |
res.code | Integer | レスポンスのステータスコード。何も投稿しなかったときは0 |
req | Object | via(webhookかtoken)、トークンのときはchannelとapi_url、text、notesの件数。WebhookのURLとトークンは含まない |
rt | Duration | ステップにかかった時間 |
status | Integer | 0 |
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が外部アクションを解決し、照合する仕組み