Skip to content

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 ph command on your machine, to test the kit before you touch the server.
  • The kit version and its sha256 from the kit-notify-slack resource page on Tara. Use them as kit-notify-slack@<version>:<sha256>.

Choose a way ​

WaySecretSettingsChoose it when
Incoming WebhookThe webhook URL https://hooks.slack.com/services/…None. The webhook decides the channelYou want the simplest setup and one fixed channel
BotThe 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 ​

  1. Open https://api.slack.com/apps and sign in to the workspace.
  2. Choose Create New App, then From scratch.
  3. Enter an App Name, for example PhillipCLI Alerts, and pick the workspace.
  4. Choose Create App.
Illustration, the real screen may differ slightly. Choose From scratch (1), enter the app name and workspace, then choose Create App (2).

2a. Way A: Incoming Webhook ​

  1. In the app, open Incoming Webhooks and turn Activate Incoming Webhooks to On.
  2. Choose Add New Webhook to Workspace.
  3. Pick the channel that receives the alerts, then choose Allow.
  4. 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.
Turn Activate Incoming Webhooks on (1), choose Add New Webhook and pick the channel (2), then copy the Webhook URL (3).

You need no settings with a webhook. Skip to step 3.

2b. Way B: bot token ​

  1. In the app, open OAuth & Permissions.
  2. Under Bot Token Scopes, choose Add an OAuth Scope and add chat:write.
  3. Add channels:read too, so check() can read the channel name. For a private channel, add groups:read instead.
  4. Choose Install to Workspace (or Reinstall after you add scopes), then Allow.
  5. Copy the Bot User OAuth Token. It starts with xoxb-.
Add the chat:write and channels:read scopes (1), install the app in the workspace (2), then copy the Bot User OAuth Token xoxb-… (3).

Next, invite the bot to the channel and find the channel ID.

  1. In the channel, type /invite @<app name> and send it. Without this the bot gets not_in_channel.
  2. Click the channel name at the top of the channel, then open the About tab.
  3. At the bottom, copy the Channel ID. It starts with C, for example C0123456789.
Channel ID is at the bottom of the About tab in the channel details (1).

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>.

bash
PHILLIP_KIT_TOKEN=<webhook URL or bot token> ph kit check kit-notify-slack --set channel=<channel ID> --send "test"
  • With a bot token, --live calls check() (auth.test and conversations.info) and sends nothing. The result looks like bot name → #channel.
  • With a webhook, check() only validates the format, because Slack gives no way to check a webhook without sending. Use --send for 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.

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>"}}
ServiceKitsDefault settingsSecret
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 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.

  1. 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.
  2. Choose the Organization and the Plugin kit-notify-slack.
  3. In Organization-specific settings, enter one name=value per line, for example channel=C0123456789. Leave it empty with a webhook.
  4. Choose the events to receive, then save.
  5. In the row's actions menu, choose Send test.
Enter channel=C… in Organization-specific settings (1), choose the events (2), then choose Save (3). Send a test from the channel row's actions menu.

You can do the same from the command line:

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

Troubleshooting ​

Error textCauseFix
the Slack secret is missing: an Incoming Webhook URL or a bot token (xoxb-…)The secret variable is empty or has the wrong nameSet <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_SLACK and restart
settings.channel (channel ID, for example C0123456789) is missing when using a bot tokenBot token without a channelAdd channel with the C… ID
Slack: not_in_channel (invite the bot to the channel: /invite @bot)The bot is not in the channelSend /invite @<app name> in the channel
Slack: channel_not_foundWrong channel ID, or a private channel the bot cannot seeCopy the ID again from the About tab, invite the bot, and add groups:read for a private channel
Slack: is_archivedThe channel is archivedUnarchive it or choose another channel
Slack: invalid_authThe token is wrong or was revokedCopy the Bot User OAuth Token again, or reinstall the app
Slack: missing_scopeThe app lacks a scopeAdd 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 removedCreate a new webhook and update the secret
Slack rejected the webhook (HTTP 401) or (HTTP 403)The webhook URL is wrongCopy the URL again
could not reach SlackThe server cannot reach SlackOpen 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 downWait. Tara retries up to 8 times

Limits ​

  • One destination per configuration: the webhook's channel, or one channel ID.
  • 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 to address because the message goes to the shared channel.
  • Messages carry metadata and links only, never the content of work.

Further reading ​