Bỏ qua, đến phần nội dung

Cài thông báo Slack ​

Hướng dẫn này nối kit kit-notify-slack vào một kênh Slack. Xong rồi, Tara, Ryoma hoặc Bandum sẽ đăng cảnh báo và sự kiện duyệt bài vào kênh đó. Bạn mất chừng mười phút.

Về các hình

Các hình là hình minh họa, chỉ cho bạn thấy cần bấm vào đâu. Slack và Portal thỉnh thoảng đổi giao diện nên màn hình thật có thể hơi khác. Tên nút thì không đổi.

Dành cho ai ​

  • Quản trị viên cài kit thông báo lên máy chủ (xem Thông báo).
  • Admin của Slack workspace, hoặc người được phép cài app vào workspace.

Trước khi bắt đầu ​

  • Một Slack workspace nơi bạn được tạo app, và một kênh nhận cảnh báo.
  • Lệnh ph trên máy của bạn, để thử kit trước khi đụng vào máy chủ.
  • Version và sha256 của kit trên trang tài nguyên kit-notify-slack của Tara. Bạn dùng chúng dưới dạng kit-notify-slack@<version>:<sha256>.

Chọn cách nối ​

CáchBí mậtSettingsNên chọn khi
Incoming WebhookURL webhook https://hooks.slack.com/services/…Không cần. Webhook quyết định kênhBạn muốn cài đơn giản nhất và chỉ cần một kênh cố định
BotBot User OAuth Token xoxb-…channel, ID kênh C…Mỗi tổ chức cần kênh riêng, hoặc bạn muốn check() xác nhận được kênh

Cả hai cách đều bắt đầu từ cùng một app.

1. Tạo Slack app ​

  1. Mở https://api.slack.com/apps và đăng nhập vào workspace.
  2. Chọn Create New App, rồi From scratch.
  3. Nhập App Name, ví dụ PhillipCLI Alerts, và chọn workspace.
  4. Chọn Create App.
Hình minh họa, màn hình thật có thể hơi khác. Chọn From scratch (1), nhập tên app và chọn workspace, rồi bấm Create App (2).

2a. Cách A: Incoming Webhook ​

  1. Trong app, mở Incoming Webhooks và gạt Activate Incoming Webhooks sang On.
  2. Chọn Add New Webhook to Workspace.
  3. Chọn kênh nhận cảnh báo, rồi chọn Allow.
  4. Chép Webhook URL. URL bắt đầu bằng https://hooks.slack.com/services/. URL này là bí mật: ai có nó đều đăng được vào kênh.
Bật Activate Incoming Webhooks (1), bấm Add New Webhook rồi chọn kênh (2), sau đó chép Webhook URL (3).

Dùng webhook thì bạn không cần settings nào. Bạn nhảy tới bước 3.

2b. Cách B: token bot ​

  1. Trong app, mở OAuth & Permissions.
  2. Ở Bot Token Scopes, chọn Add an OAuth Scope và thêm chat:write.
  3. Thêm cả channels:read để check() đọc được tên kênh. Với kênh riêng tư, thêm groups:read.
  4. Chọn Install to Workspace (hoặc Reinstall sau khi thêm scope), rồi chọn Allow.
  5. Chép Bot User OAuth Token. Token bắt đầu bằng xoxb-.
Thêm scope chat:write và channels:read (1), cài app vào workspace (2), rồi chép Bot User OAuth Token xoxb-… (3).

Tiếp theo, bạn mời bot vào kênh và lấy ID kênh.

  1. Trong kênh, gõ /invite @<tên app> rồi gửi. Không làm bước này thì bot báo not_in_channel.
  2. Bấm vào tên kênh ở đầu kênh, rồi mở tab About.
  3. Ở cuối tab, chép Channel ID. ID bắt đầu bằng C, ví dụ C0123456789.
Channel ID nằm ở cuối tab About trong phần chi tiết kênh (1).

3. Thử kit bằng ph kit check ​

Bạn đưa bí mật qua biến PHILLIP_KIT_TOKEN, không bao giờ đưa qua tham số. Lệnh ph kit check nhận thư mục kit hoặc tên[@version], các --set key=value (lặp được), --live và --send <text>.

bash
PHILLIP_KIT_TOKEN=<webhook URL or bot token> ph kit check kit-notify-slack --set channel=<channel ID> --send "test"
  • Với token bot, --live gọi check() (auth.test và conversations.info) mà không gửi gì. Kết quả có dạng bot tên → #kênh.
  • Với webhook, check() chỉ kiểm định dạng, vì Slack không cho kiểm webhook mà không gửi. Bạn dùng --send để thử thật, và bỏ --set channel.

4. Cấu hình dịch vụ ​

Tara, Ryoma và Bandum dùng chung một kit. Mỗi dịch vụ có tiền tố biến riêng. Ví dụ dưới đây là cho Ryoma với token bot. Bạn lấy <version> và <sha256> trên trang tài nguyên của Tara. Với webhook, bạn đặt URL vào bí mật và bỏ phần settings.

bash
RYOMA_NOTIFY_PLUGINS=kit-notify-slack@<version>:<sha256>
RYOMA_NOTIFY_SECRET_KIT_NOTIFY_SLACK=<webhook URL or bot token>
RYOMA_NOTIFY_SETTINGS={"kit-notify-slack":{"channel":"<channel ID>"}}
Dịch vụKitSettings mặc địnhBí mật
TaraTARA_NOTIFY_PLUGINSTARA_NOTIFY_SETTINGSTARA_NOTIFY_SECRET_KIT_NOTIFY_SLACK
RyomaRYOMA_NOTIFY_PLUGINSRYOMA_NOTIFY_SETTINGSRYOMA_NOTIFY_SECRET_KIT_NOTIFY_SLACK
BandumBANDUM_NOTIFY_PLUGINSBANDUM_NOTIFY_SETTINGSBANDUM_NOTIFY_SECRET_KIT_NOTIFY_SLACK

Tara còn cần TARA_NOTIFY_TOKEN, token Tara chỉ đọc để tải gói kit. Đổi biến xong, bạn khởi động lại dịch vụ. Các biến còn lại có trong trang Thông báo.

5. Chọn kênh cho từng tổ chức ​

Bí mật chỉ có một cho mỗi kit trên máy chủ. Với webhook, webhook quyết định kênh nên mọi tổ chức đều đăng vào cùng một chỗ. Muốn mỗi tổ chức một kênh riêng, bạn dùng token bot và đặt channel cho từng tổ chức.

  1. Đăng nhập Portal bằng tài khoản owner hoặc admin của tổ chức. Mở menu tài khoản, chọn Admin, rồi Notifications, rồi thêm một kênh.
  2. Chọn Organization và Plugin là kit-notify-slack.
  3. Trong Organization-specific settings, nhập mỗi dòng một cặp name=value, ví dụ channel=C0123456789. Dùng webhook thì để trống.
  4. Chọn các sự kiện muốn nhận rồi lưu.
  5. Ở menu thao tác của dòng, chọn Send test.
Nhập channel=C… vào Organization-specific settings (1), chọn sự kiện (2), rồi bấm Save (3). Gửi thử bằng menu thao tác ở dòng của kênh.

Bạn cũng làm được việc này bằng dòng lệnh:

bash
ph tara notify set <org> kit-notify-slack --set channel=<channel ID> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-slack

Xử lý lỗi ​

Nội dung lỗiNguyên nhânCách sửa
the Slack secret is missing: an Incoming Webhook URL or a bot token (xoxb-…)Biến bí mật trống hoặc đặt sai tênĐặt <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_SLACK rồi khởi động lại
settings.channel (channel ID, for example C0123456789) is missing when using a bot tokenDùng token bot mà thiếu kênhThêm channel với ID dạng C…
Slack: not_in_channel (invite the bot to the channel: /invite @bot)Bot chưa vào kênhGửi /invite @<tên app> trong kênh
Slack: channel_not_foundID kênh sai, hoặc kênh riêng tư mà bot không thấyChép lại ID ở tab About, mời bot, và thêm groups:read với kênh riêng tư
Slack: is_archivedKênh đã lưu trữBỏ lưu trữ hoặc chọn kênh khác
Slack: invalid_authToken sai hoặc đã bị thu hồiChép lại Bot User OAuth Token, hoặc cài lại app
Slack: missing_scopeApp thiếu một scopeThêm scope ở Bot Token Scopes rồi cài lại app
the webhook no longer exists (HTTP 404) hoặc (HTTP 410)Webhook đã bị xóa hoặc app đã bị gỡTạo webhook mới và cập nhật bí mật
Slack rejected the webhook (HTTP 401) hoặc (HTTP 403)URL webhook saiChép lại URL
could not reach SlackMáy chủ không gọi tới được SlackMở đường mạng, hoặc đặt apiUrl về proxy nội bộ
Slack is temporarily failing (HTTP 429) hoặc (HTTP 5xx)Slack giới hạn tốc độ hoặc đang lỗiChờ. Tara thử lại tối đa 8 lần

Giới hạn ​

  • Mỗi cấu hình chỉ có một đích: kênh của webhook, hoặc một ID channel.
  • Tin nhắn bị cắt ở 3900 ký tự. Tiêu đề in đậm ở dòng đầu.
  • Tắt xem trước liên kết.
  • Kit bỏ qua địa chỉ to, vì tin đi vào kênh chung.
  • Tin chỉ chứa siêu dữ liệu và liên kết, không bao giờ có nội dung công việc.

Đọc thêm ​