How to use notify_slack

In this article, I will introduce how to use notify_slack and other related information.

catatsuy/notify_slack

Since notify_slack has had new features added and there have been changes to the Slack specifications, I will briefly summarize the current situation (as of 2020/07/26).

I would be happy if this could be widely used as a convenient CLI tool for posting to Slack, such as for information sharing during ISUCON.

Design Philosophy

"Keep it simple," "Don't make the user worry about details when using it," and "Provide a CLI to post to Slack"

are the core design philosophies I use for development.

Features

There are two main features.

• Post the content of a command's standard output to Slack once per second (frequency is customizable)
  • This is called the streaming feature.
  • Since tee is implemented internally, the output to the screen does not stop.
• Upload a file to Slack as a Snippet
  • This is called the snippet posting feature.

The streaming feature is hard to explain in words, so please take a look at the YouTube video.

Each feature can be used with commands like the following:

./deploy.sh | notify_slack
notify_slack README.md

Slack has a feature that applies syntax highlighting based on the file extension when passing a filename. I recommend uploading with an appropriate extension.

If you want to pass the content to be posted as a snippet via a pipe, you can use the -snippet option.

In that case, it is strongly recommended to pass either the -filename or -filetype option.

If you provide an appropriate -filetype option, Slack will apply syntax highlighting. If you specify a filename including the extension in -filename, -filetype will be automatically determined. Therefore, my personal recommendation is to specify the filename including the extension with -filename and omit the -filetype option.

Refer to the Slack documentation for available -filetype values. The command would look like this:

git diff | ./bin/notify_slack -snippet -filename git.diff

Installation

I recommend using the binaries distributed on GitHub Releases. Please download and use the latest version.

If you have a Go development environment, you can also install it by compiling it yourself.

GO111MODULE=on go get github.com/catatsuy/notify_slack/cmd/notify_slack

Configuration

Prepare a configuration file in TOML format. The configuration file is loaded in the following order, using the first one found:

1. The file specified by the -c option
2. $HOME/.notify_slack.toml
3. $HOME/etc/notify_slack.toml
4. /etc/notify_slack.toml

My personal recommendation is to use $HOME/.notify_slack.toml on your local machine and /etc/notify_slack.toml for server use.

The configuration file looks like this:

[slack]
url = "https://hooks.slack.com/services/**"
token = "xoxp-xxxxx"
channel = "#general"

The streaming feature uses Incoming Webhooks, and the snippet posting feature uses the Slack API's files.upload.

If you are unsure how to use it, you should be able to understand it by looking up the Slack API specifications. I will explain the options below.

Explanation of Options

url specifies the Incoming Webhooks URL. This option is mandatory when using the streaming feature. If you only use the streaming feature, you can run it by passing only this option.

token is set when using the snippet posting feature. Please note that channel or snippet_channel is also required for the snippet posting feature. The creation method for tokens has changed many times. Please refer to catatsuy/notify_slack: post to Slack on the command line for instructions on how to create one. I try to keep it updated as much as possible. The procedure is a bit complicated, but you might find the latest information by searching for things like "Slack Apps."

channel is used to specify the destination channel. It is used for both the streaming and snippet posting features. Note that while old Incoming Webhooks allowed you to change the channel freely, new Incoming Webhooks only allow posting to the pre-configured channel. If no channel is specified for Incoming Webhooks, it will post to the default channel. Since the Slack API does not have the concept of a default channel, you must always specify a channel for snippet posting.

snippet_channel is used to specify the channel for the snippet posting feature. If only channel is specified, the snippet posting feature will use channel. However, if snippet_channel is also specified, the snippet posting feature will prioritize snippet_channel.

These are the important options. If you want to know about other options, please check README.md.

Additionally, all options can be passed as command-line arguments. If passed via command-line, those take priority. There is also a feature to pass these options via environment variables, which is useful when you want to use it in containers.

Specific Usage Examples

How my team fights in ISUCON | by catatsuy | Medium

This article introduces specific usage examples. We use the streaming feature for deployment script logs and the snippet posting feature for sharing access log aggregation results or slow query analysis results.

There are many other possible ways to use it. If you find a good use case, please share it on your blog or elsewhere.

Also, if there are any features you would like to see, please let me know. I cannot guarantee implementation, but if I think it should be implemented, I might do it. Pull requests are also welcome.