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
phtrê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-slackcủa Tara. Bạn dùng chúng dưới dạngkit-notify-slack@<version>:<sha256>.
Chọn cách nối
| Cách | Bí mật | Settings | Nên chọn khi |
|---|---|---|---|
| Incoming Webhook | URL webhook https://hooks.slack.com/services/… | Không cần. Webhook quyết định kênh | Bạn muốn cài đơn giản nhất và chỉ cần một kênh cố định |
| Bot | Bot 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
- Mở
https://api.slack.com/appsvà đăng nhập vào workspace. - Chọn Create New App, rồi From scratch.
- Nhập App Name, ví dụ
PhillipCLI Alerts, và chọn workspace. - Chọn Create App.
2a. Cách A: Incoming Webhook
- Trong app, mở Incoming Webhooks và gạt Activate Incoming Webhooks sang On.
- Chọn Add New Webhook to Workspace.
- Chọn kênh nhận cảnh báo, rồi chọn Allow.
- 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.
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
- Trong app, mở OAuth & Permissions.
- Ở Bot Token Scopes, chọn Add an OAuth Scope và thêm
chat:write. - Thêm cả
channels:readđểcheck()đọc được tên kênh. Với kênh riêng tư, thêmgroups:read. - Chọn Install to Workspace (hoặc Reinstall sau khi thêm scope), rồi chọn Allow.
- Chép Bot User OAuth Token. Token bắt đầu bằng
xoxb-.
Tiếp theo, bạn mời bot vào kênh và lấy ID kênh.
- Trong kênh, gõ
/invite @<tên app>rồi gửi. Không làm bước này thì bot báonot_in_channel. - Bấm vào tên kênh ở đầu kênh, rồi mở tab About.
- Ở cuối tab, chép Channel ID. ID bắt đầu bằng
C, ví dụC0123456789.
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>.
PHILLIP_KIT_TOKEN=<webhook URL or bot token> ph kit check kit-notify-slack --set channel=<channel ID> --send "test"- Với token bot,
--livegọicheck()(auth.testvàconversations.info) mà không gửi gì. Kết quả có dạngbot 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.
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ụ | Kit | Settings mặc định | Bí mật |
|---|---|---|---|
| Tara | TARA_NOTIFY_PLUGINS | TARA_NOTIFY_SETTINGS | TARA_NOTIFY_SECRET_KIT_NOTIFY_SLACK |
| Ryoma | RYOMA_NOTIFY_PLUGINS | RYOMA_NOTIFY_SETTINGS | RYOMA_NOTIFY_SECRET_KIT_NOTIFY_SLACK |
| Bandum | BANDUM_NOTIFY_PLUGINS | BANDUM_NOTIFY_SETTINGS | BANDUM_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.
- Đă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.
- Chọn Organization và Plugin là
kit-notify-slack. - 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. - Chọn các sự kiện muốn nhận rồi lưu.
- Ở menu thao tác của dòng, chọn Send test.
Bạn cũng làm được việc này bằng dòng lệnh:
ph tara notify set <org> kit-notify-slack --set channel=<channel ID> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-slackXử lý lỗi
| Nội dung lỗi | Nguyên nhân | Cá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 token | Dùng token bot mà thiếu kênh | Thê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ênh | Gửi /invite @<tên app> trong kênh |
Slack: channel_not_found | ID kênh sai, hoặc kênh riêng tư mà bot không thấy | Chép lại ID ở tab About, mời bot, và thêm groups:read với kênh riêng tư |
Slack: is_archived | Kênh đã lưu trữ | Bỏ lưu trữ hoặc chọn kênh khác |
Slack: invalid_auth | Token sai hoặc đã bị thu hồi | Chép lại Bot User OAuth Token, hoặc cài lại app |
Slack: missing_scope | App thiếu một scope | Thê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 sai | Chép lại URL |
could not reach Slack | Máy chủ không gọi tới được Slack | Mở đườ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ỗi | Chờ. 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.