qxmips/slack-plugin

A Jenkins plugin for posting notifications to a Slack channel

Slack plugin for Jenkins

(click to sign up)

Provides Jenkins notification integration with Slack or Slack compatible applications like RocketChat and Mattermost.

Install Instructions for Slack

1. Get a Slack account: https://slack.com/

2. Configure the Jenkins integration: https://my.slack.com/services/new/jenkins-ci

3. Install this plugin on your Jenkins server:

   1. From the Jenkins homepage navigate to Manage Jenkins
   2. Navigate to Manage Plugins,
   3. Change the tab to Available,
   4. Search for slack,
   5. Check the box next to install.

Freestyle job

1. Configure it in your Jenkins job (and optionally as global configuration) and add it as a Post-build action.

Pipeline job

slackSend color: 'good', message: 'Message from Jenkins Pipeline'

Additionally you can pass attachments or blocks in order to send complex messages, for example:

def attachments = [
  [
    text: 'I find your lack of faith disturbing!',
    fallback: 'Hey, Vader seems to be mad at you.',
    color: '#ff0000'
  ]
]

slackSend(channel: '#general', attachments: attachments)

blocks = [
	[
		"type": "section",
		"text": [
			"type": "mrkdwn",
			"text": "Hello, Assistant to the Regional Manager Dwight! *Michael Scott* wants to know where you'd like to take the Paper Company investors to dinner tonight.\n\n *Please select a restaurant:*"
		]
	],
    [
		"type": "divider"
	],
	[
		"type": "section",
		"text": [
			"type": "mrkdwn",
			"text": "*Farmhouse Thai Cuisine*\n:star::star::star::star: 1528 reviews\n They do have some vegan options, like the roti and curry, plus they have a ton of salad stuff and noodles can be ordered without meat!! They have something for everyone here"
		],
		"accessory": [
			"type": "image",
			"image_url": "https://s3-media3.fl.yelpcdn.com/bphoto/c7ed05m9lC2EmA3Aruue7A/o.jpg",
			"alt_text": "alt text for image"
		]
	]
]

slackSend(channel: '#general', blocks: blocks)

For more information about slack messages see Slack Messages Api, Slack attachments Api and Block kit

Note the attachments API is classified as legacy, with blocks as the replacement.

File upload

You can upload files to slack with this plugin:

node {
  sh "echo hey > blah.txt"
  slackUploadFile filePath: '*.txt', initialComment:  'HEY HEY'
}

This feature requires botUser mode.

Threads Support

You can send a message and create a thread on that message using the pipeline step. The step returns an object which you can use to retrieve the thread ID. Send new messages with that thread ID as the target channel to create a thread. All messages of a thread should use the same thread ID.

Example:

def slackResponse = slackSend(channel: "cool-threads", message: "Here is the primary message")
slackSend(channel: slackResponse.threadId, message: "Thread reply #1")
slackSend(channel: slackResponse.threadId, message: "Thread reply #2")

This feature requires botUser mode.

Messages that are posted to a thread can also optionally be broadcasted to the channel. Set replyBroadcast: true to do so. For example:

def slackResponse = slackSend(channel: "ci", message: "Started build")
slackSend(channel: slackResponse.threadId, message: "Build still in progress")
slackSend(
    channel: slackResponse.threadId,
    replyBroadcast: true,
    message: "Build failed. Broadcast to channel for better visibility."
)

Unfurling Links

You can allow link unfurling if you send the message as text. This only works in a text message, as attachments cannot be unfurled.

Example:

slackSend(channel: "news-update", message: "https://www.nytimes.com", sendAsText: true)

Install Instructions for Slack compatible application

1. Log into Slack compatible application.
2. Create a Webhook (it may need to be enabled in system console) by visiting Integrations.
3. You should now have a URL with a token. Something like https://mydomain.com/hooks/xxxx where xxxx is the integration token and https://mydomain.com/hooks/ is the Slack compatible app URL.
4. Install this plugin on your Jenkins server.
5. Configure it in your Jenkins job (and optionally as global configuration) and add it as a Post-build action.

If you want to configure a notification to be sent to Slack for all jobs, you may want to also consider installing an additional plugin called Global Slack Notifier plugin.

Security

Use Jenkins Credentials and a credential ID to configure the Slack integration token. It is a security risk to expose your integration token using the previous Integration Token setting.

Create a new Secret text credential:

Select that credential as the value for the Integration Token Credential ID field:

Direct Message

You can send messages to channels or you can notify individual users via their slackbot. In order to notify an individual user, use the syntax @user_id in place of the project channel. Mentioning users by display name may work, but it is not unique and will not work if it is an ambiguous match.

Bot user option

This plugin supports sending notifications via bot users. You can enable bot user support from both global and project configurations. If the notification will be sent to a user via direct message, default integration sends it via @slackbot. You can use this option if you want to send messages via a bot user. You need to provide the Bot User OAuth Access Token credential as the integration token credentials to use this feature.

The bot user option is not supported if you use the Slack compatible app URL option.

Configuration as code

This plugin supports configuration as code Add to your yaml file:

credentials:
  system:
    domainCredentials:
      - credentials:
          - string:
              scope: GLOBAL
              id: slack-token
              secret: '${SLACK_TOKEN}'
              description: Slack token


unclassified:
  slackNotifier:
    teamDomain: <your-slack-workspace-name> # i.e. your-company (just the workspace name not the full url)
    tokenCredentialId: slack-token

For more details see the configuration as code plugin documentation: https://github.com/jenkinsci/configuration-as-code-plugin#getting-started

Developer instructions

Install Maven and JDK.

$ mvn -version | grep -v home
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T08:41:47-08:00)
Java version: 1.7.0_79, vendor: Oracle Corporation
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "4.4.0-65-generic", arch: "amd64", family: "unix"

Run unit tests

mvn test

Create an HPI file to install in Jenkins (HPI file will be in target/slack.hpi).

mvn clean package