Set up Slack notifications
This guide connects the kit-notify-slack kit to a Slack channel. After it, Tara, Ryoma, or Bandum can post alerts and review events into that channel. It takes about ten minutes.
About the pictures
The figures are illustrations that show where to click. Slack and the Portal change their screens from time to time, so the real screen may look a little different. The names of the buttons stay the same.
Who this is for
- An administrator who installs notification kits on a server (see Notifications).
- A Slack workspace admin, or someone who may install apps in the workspace.
Before you start
- A Slack workspace where you may create apps, and a channel for the alerts.
- The
phcommand on your machine, to test the kit before you touch the server. - The kit version and its sha256 from the
kit-notify-slackresource page on Tara. Use them askit-notify-slack@<version>:<sha256>.
Choose a way
| Way | Secret | Settings | Choose it when |
|---|---|---|---|
| Incoming Webhook | The webhook URL https://hooks.slack.com/services/… | None. The webhook decides the channel | You want the simplest setup and one fixed channel |
| Bot | The Bot User OAuth Token xoxb-… | channel, the channel ID C… | Each organization needs its own channel, or you want check() to verify the channel |
Both ways start with the same app.
1. Create the Slack app
- Open
https://api.slack.com/appsand sign in to the workspace. - Choose Create New App, then From scratch.
- Enter an App Name, for example
PhillipCLI Alerts, and pick the workspace. - Choose Create App.
2a. Way A: Incoming Webhook
- In the app, open Incoming Webhooks and turn Activate Incoming Webhooks to On.
- Choose Add New Webhook to Workspace.
- Pick the channel that receives the alerts, then choose Allow.
- Copy the Webhook URL. It starts with
https://hooks.slack.com/services/. The URL is a secret: anyone who has it can post to the channel.
You need no settings with a webhook. Skip to step 3.
2b. Way B: bot token
- In the app, open OAuth & Permissions.
- Under Bot Token Scopes, choose Add an OAuth Scope and add
chat:write. - Add
channels:readtoo, socheck()can read the channel name. For a private channel, addgroups:readinstead. - Choose Install to Workspace (or Reinstall after you add scopes), then Allow.
- Copy the Bot User OAuth Token. It starts with
xoxb-.
Next, invite the bot to the channel and find the channel ID.
- In the channel, type
/invite @<app name>and send it. Without this the bot getsnot_in_channel. - Click the channel name at the top of the channel, then open the About tab.
- At the bottom, copy the Channel ID. It starts with
C, for exampleC0123456789.
3. Test the kit with ph kit check
Pass the secret through the PHILLIP_KIT_TOKEN variable, never as an argument. The command ph kit check takes a kit folder or name[@version], repeated --set key=value, --live, and --send <text>.
PHILLIP_KIT_TOKEN=<webhook URL or bot token> ph kit check kit-notify-slack --set channel=<channel ID> --send "test"- With a bot token,
--livecallscheck()(auth.testandconversations.info) and sends nothing. The result looks likebot name → #channel. - With a webhook,
check()only validates the format, because Slack gives no way to check a webhook without sending. Use--sendfor a real test, and leave out--set channel.
4. Configure the service
Tara, Ryoma, and Bandum use the same kit. Each service has its own variable prefix. The example below is for Ryoma with a bot token. Take <version> and <sha256> from the Tara resource page. With a webhook, put the URL in the secret and leave out the 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>"}}| Service | Kits | Default settings | Secret |
|---|---|---|---|
| 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 also needs TARA_NOTIFY_TOKEN, a read-only Tara token that downloads the kit package. Restart the service after you change the variables. For the other variables, see Notifications.
5. Choose the channel for each organization
The secret stays one per kit on the server. With a webhook, the webhook decides the channel, so every organization posts to the same place. To give each organization its own channel, use a bot token and set channel per organization.
- Sign in to the Portal as an owner or admin of the organization. Open the account menu, then Admin, then Notifications, then add a channel.
- Choose the Organization and the Plugin
kit-notify-slack. - In Organization-specific settings, enter one
name=valueper line, for examplechannel=C0123456789. Leave it empty with a webhook. - Choose the events to receive, then save.
- In the row's actions menu, choose Send test.
You can do the same from the command line:
ph tara notify set <org> kit-notify-slack --set channel=<channel ID> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-slackTroubleshooting
| Error text | Cause | Fix |
|---|---|---|
the Slack secret is missing: an Incoming Webhook URL or a bot token (xoxb-…) | The secret variable is empty or has the wrong name | Set <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_SLACK and restart |
settings.channel (channel ID, for example C0123456789) is missing when using a bot token | Bot token without a channel | Add channel with the C… ID |
Slack: not_in_channel (invite the bot to the channel: /invite @bot) | The bot is not in the channel | Send /invite @<app name> in the channel |
Slack: channel_not_found | Wrong channel ID, or a private channel the bot cannot see | Copy the ID again from the About tab, invite the bot, and add groups:read for a private channel |
Slack: is_archived | The channel is archived | Unarchive it or choose another channel |
Slack: invalid_auth | The token is wrong or was revoked | Copy the Bot User OAuth Token again, or reinstall the app |
Slack: missing_scope | The app lacks a scope | Add the scope under Bot Token Scopes and reinstall the app |
the webhook no longer exists (HTTP 404) or (HTTP 410) | The webhook was deleted or the app was removed | Create a new webhook and update the secret |
Slack rejected the webhook (HTTP 401) or (HTTP 403) | The webhook URL is wrong | Copy the URL again |
could not reach Slack | The server cannot reach Slack | Open the network route, or set apiUrl to your internal proxy |
Slack is temporarily failing (HTTP 429) or (HTTP 5xx) | Slack limits the rate or is down | Wait. Tara retries up to 8 times |
Limits
- One destination per configuration: the webhook's channel, or one
channelID. - A message is cut at 3900 characters. The subject is shown in bold on the first line.
- Link previews are off.
- The kit ignores the
toaddress because the message goes to the shared channel. - Messages carry metadata and links only, never the content of work.