Slack notifications in Jenkins

One of the most important things in Jenkins is the ability to being extended by plugins. Jenkins is an Open Source project, so we can see what happens inside, and we can not only contribute to the Jenkins core but also create our own plugins. But the popularity of Jenkins causes that many functionalities that we would like to implement, have been already developed! This situation we have with Slack – if we want Slack notifications in Jenkins, then we can just use a Slack plugin! When I’m writing this post, the Slack plugin is actively maintained.

Why should I want to have Slack notifications in Jenkins?

Slack in the IT industry is one of the most often chosen communicators. Of course, we have many others like Microsoft Teams, Rocket, and so on, but it seems that the Slack plugin is the most installed integration for communicators in Jenkins. To be honest, this paragraph should be named in another way – why should I want to have notifications in my company’s communicator. This is very important to have as much information in one place, so if most communication is conducted on Slack/RocketChat/Teams, then you should also add Jenkins notifications to your communicator.

You can then avoid missing something important, like build failure or information about back to normal. It’s very annoying when I need to check multiple sources of data, like Slack, Teams, e-mails, JIRA comments, and so on. I’d like to have everything in one place, even if it’s only a hyperlink to the destination’s source. It’s fine for me – I’ll check details on Jenkins/JIRA/GCP projects or anything else. I just want to be informed about everything in one place. So that’s why I want to have Slack notifications in Jenkins – to be informed about failures in one place.

So how can I integrate Jenkin with Slack?

This is a very simple integration, but you need to do some steps on both sides – Jenkins and Slack. You need to install Slack plugin, create an Incoming Webhook in your Slack’s workspace, and then configure the Slack plugin. So let’s start from the beginning.

New Incoming Webhook

This part is built from two steps:

  1. new channel creation
  2. new Incoming Webhook creation

Each Incoming Webhook integration should be connected with one channel. You can create a channel during the integration configuration, but it’s good to have one before. In this article channel, that will be receiving all Jenkins notifications will be named… jenkins.Yup, just Jenkins. So create this channel (no matter whether it’s a private or public channel) and once you’re ready, go to the Slack application management page. You can find that under the following URL:

There you should choose Custom Integrations from the left menu and click on Incoming WebHooks.

⚠️Small digression. There is an App in the Slack apps directory, that allows integrating with Jenkins without Custom WebHooks. the problem is that it needs another plugin and doesn’t have so much flexibility as this one. So that’s why I decided to use this plugin and I have to use an Incoming WebHook. ⚠️

Now you should see something like this:

Slack notifications in Jenkins – Incoming WebHooks

Now you just need to choose the “Add to Slack” button and you will be redirected to the panel where you need to choose your channel. In our case, it’s the “jenkins” channel. As you can see, there is also a possibility to create a new channel. Once you choose the channel, just simply click the “Add Incoming WebHooks integration” button.

Incoming WebHook creation

You will see some details about this integration with the possibility to customize some things (like the name of the integration). One of the most important thing there is the Webhook URL:

Slack WebHook URL

It will be used by Slack plugin to sending messages, but you should keep this URL in secret! Anyone that has the URL is able to use Slack’s API and manipulate your Slack (sending messages to the channel, adding reactions, and so on). So it’s very important to keep it secret!

Ok, so that’s all in the Slack part. Now we can move forward to the next step of our Slack notifications in Jenkins configuration.

Install Slack plugin in Jenkins

Slack plugin installation doesn’t differ from any other plugin. Just go to the Plugin Manager, choose the Available tab, and type into the search box “slack”. You will see a similar list of plugins:

Slack Plugins list

Now it’s very important to choose the valid plugin. It’s the “Slack Notification”:

Valid Slack plugin in Jenkins

Now mark the checkbox and install the plugin and other important things.

Configure credentials with Slack hook

Do you remember the hook creation? This is the time when you need to secure part of your token. You probably want to avoid usage of this webhook by unauthorized people, right? I assume that I’m right. Hence, you shouldn’t add the whole webhook to the configuration as a plain text. Jenkins credentials are the best idea to secure your configuration because the Slack Notification plugin supports credentials usage.

To check how to add new credentials you can check my other article, where I described in detail the whole process.

Once you know how to do that, create a new credential of type “Secret text”, that contains the whole hash after https://hook.slack.com/services/

Slack notifications in Jenkins – credentials

Configure the plugin for Slack notifications in Jenkins

Now it’s time to configure our Jenkins! We’ll start from the Plugin configuration, and then we can move forward to the job configuration! Main configuration you can find in Manage Jenkins -> Configure System. Exactly like most of the configs. The Slack section is placed almost on the bottom of the page, so please scroll down. There are a few fields, that you must fill in.

Jenkins notifications Slack configuration

There you have a view of all options, after clicking the “Advanced” button. As you can see, you don’t have to fill each field – to be honest, these four things should be enough.

  • Credentials
  • Default channel
  • Username
  • Override URL

“Credentials” should contain your secured party of the Slack webhook – so you should choose the credential with this token. The “Default channel” is obvious – the name of the channel, where slack notifications in Jenkins will land. “Username” is just the name of the user that is visible on the channel with notification. And “Override URL” is the first part of the configured hook – without the token-like part. Once you fill all the needed fields, you can push the “Test connection” button to check whether your integration is configured properly. If yes, you should see a similar message on the configured channel:

Jenkins channel notification on Slack

My first job

Once we have Slack Plugin installed and configured, we can now move to the job configuration. It’s also easy and very quick. Let’s see how it looks on the Freestyle job example.

Create a new job and go to the bottom, to the post-build action. After you click on the “Post-build action”, you’ll the drop-down list with the following possibilities (it may be different depending on your plugins and Jenkins configuration):

Jenkins post-build Slack

Choose “Slack Notification”, highlighted at the image above. You should see some fields to fill up. Please take a look at the examples below – I filled them up with some samples:

Slack plugin configuration 1
Slack plugin configuration 2
Slack plugin configuration 3

This scenario has the following assumptions:

  1. Notification should be sent when a job fails.
  2. Notification should be sent when a job backs to normal.
  3. Notifications should be sent when a job ends with success.

Also, messages for “Success” and “Fail” are customized. Just to have more human-friendly information. But not only – you’ll see later why I wanted to use custom messages. Anyway, if you run this job (previously add some dummy shell step like “exit 0” or something like that), you should see on your Slack channel something like this:

Slack notifications in Jenkins success test

What will happen when a job fails?

Now let’s check what will happen when a job will fail. Change your job by adding “exit 1” to the shell step, or whatever can cause a failure and run your job again. If everything is configured properly, then the notification about job failure should be sent to your Slack channel – please notice how it differs from the previous one! It has a red line and another message.

Slack notification failure test

But ok, our job failed, so we need to fix that and probably run one more time, right? Right. Do we have a possibility to identify whether the job just ended with success or have been fixed? Just from the notification Yeah! We do. If you fix your job and run, the notification should look similar to the image below:

Slack notification test back to normal

Do you see “Back to normal” status in the first line? That’s how you can identify the status od the job.

Can I mention users in slack notifications in Jenkins?

Yes, you can! It’s one of the most interesting things that you can do with those notifications. Thanks to that, the right persons can be notified about job failure. You can tell particular persons, that their part of the deployment process went wrong, so they can react immediately. But there is one, very important thing, that you need to know before you start using the mentions.

For some users, you can just use classic syntax “@username”. But it won’t work with all, especially not with the usernames with a different name and display name. The safest way of using mentions is to use an ID. According to the Slack documentation:

Use the simpler user ID-only form <@W123> instead.

So if you want to mention some user in the message, you should add something like this:

lack notification with mention

How can I get a user ID in Slack?

In a very simple way. Just go to you Slack workspace, find a profile you want to mention, and click on that profile -> “View full profile”. You should see a new column on the right side of the Slack. hen you just need to click on the three dots (like on the picture below) and you will see a “Copy member ID” field. That’s the user ID.

Slack user id

After you do the necessary configuration and run the job, new notification on Slack should contain a user mention, like on this screenshot:

Slack test mention

Can I use DSL to configure this step?

Of course, that you can! Without any problem. Why would you want to have slack notifications in Jenkins if you couldn’t add them to the code and automate the whole configuration?

The syntax is very simple. If you want to see all possible methods, you can take a look at your DSL API Viewer (YOUR_JENKINS/plugin/job-dsl/api-viewer/index.html). Slack (in the publisher context) should be placed under the following URL: YOUR_JENKINS/plugin/job-dsl/api-viewer/index.html#method/javaposse.jobdsl.dsl.helpers.publisher.PublisherContext.slackNotifier. This should be enough for fully working configuration:

Of course, you can move the whole configuration to the separate class and parameterize some values like a custom message, e.g.:

And that’s all. Enjoy your fancy Jenkins with Slack notification!

Bibliography:

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.