Setting up actionable build notifications in Slack

4 minute readExtensibilityDeveloper productivity

CloudBees CI Slack Integration sends Slack messages directly to you to notify you of relevant status information and build data at the end of the sequence, so that you know if the build was successful, and if not, the actions that need to be taken to get a failed build back on track. The notifications include information on build and test results, including direct links to results and error details.

Sending messages directly to Slack means that you do not need to switch between different tools to be alerted when builds complete, and in the case of failed builds you can take immediate action.

CloudBees CI Slack Integration feature benefits

The CloudBees CI Slack Integration feature provides the following benefits:

  • Provides feedback immediately upon completion of a build.

  • Highlights the causes of build failures quickly.

  • Limits context switching between tools.

  • Installs easily and does not require updates to Pipelines.

This feature does not require any modifications to Pipelines.
CloudBees CI Slack Integration messages are only sent for commits that have a name associated with them. For example, for GitHub, Slack Integration messages are only sent for Pull Requests - you will not get a failure notification on a branch.

The process of setting up actionable build notifications in Slack requires an Administrator to complete the following steps from Slack’s App API:

And the following steps from the CloudBees CI controller:

Supported versions

The CloudBees Slack Integration plugin is available on the following versions and platforms:

  • CloudBees CI on modern cloud platforms version 2.222.4.3 (and higher)

  • CloudBees CI on traditional platforms version 2.222.4.3 (and higher)

  • CloudBees Jenkins Platform version 2.222.4.3 (and higher)

Creating a new Slack App

The Slack App that Administrators create is a hub for messages that will be used by the CloudBees Slack Integration Plugin to notify users of information regarding builds: failures, JUnit errors, Pipeline Policy violations, or even when the build completes successfully.

The following set of instructions includes a reference implementation of the Slack API. Your experience with the Slack API may vary depending on the version you are currently using. For more information from Slack API documentation, see an introduction to Slack apps.
To create a new Slack App for CloudBees CI Slack Integration:
  1. Navigate to Slack’s App API in a browser.

  2. Select Your Apps in the top right corner.

  3. Select either Create an App if you have never created a Slack App before

    or

    Create New App if you have previously created a Slack App.

  4. Enter an App Name.

  5. Select a Development Slack Workspace from the drop-down menu.

  6. Select Create App.

  7. Select OAuth & Permissions in the left pane.

  8. Scroll down to Scopes.

  9. Select Add an OAuth Scope under Bot Token Scopes.

  10. Select and add the following scopes:

    Table 1. Scopes
    ScopeDescription

    chat:write

    Send messages as <App Name>

    chat:write.customize

    Send messages as <App Name> with a customized username and avatar

    chat:write.public

    Send messages to channels <App Name> isn’t a member of

    files:read

    View files shared in channels and conversations that <App Name> has been added to

    files:write

    Upload, edit, and delete files as <App Name>

    links:read

    View some URLs in messages

    links:write

    Show previews of URLs in messages

    users:read

    View people in the workspace

    users:read.email

    View email addresses of people in the workspace

    You must include all of the scopes listed or the Slack App will not function properly. For example, without users:read and users:read.email, the plugin won’t be able to retrieve users.

Installing the new Slack App in a client workspace

Admin privileges are required in the Slack workspace to install the new Slack App.
The following set of instructions includes a reference implementation of the Slack API. Your experience with the Slack API may vary depending on the version you are currently using. For more information from Slack API documentation, see an introduction to Slack apps.
To install the new Slack App in a client workspace:
  1. Sign in to your desired workspace.

  2. Select OAuth & Permissions in the left pane.

  3. Under OAuth Tokens & Redirect URLs select Install App to Workspace.

  4. Select Allow.

  5. Select Copy to copy the Bot User OAuth Access Token.

Installing the CloudBees Slack Integration Plugin

To install the CloudBees Slack Integration Plugin:

  1. From your CloudBees CI controller, select Manage Jenkins > Manage Plugins.

  2. Select the Available tab.

  3. Use the Filter field to search for CloudBees Slack Integration Plugin.

  4. Select the checkbox to choose the CloudBees Slack Integration Plugin.

  5. Select Download now and install after restart to install the plugin.

  6. Restart CloudBees CI.

Adding the Slack Bot Token as secret text

Adding the Slack Bot token as a secret will allow it to be stored securely within the CloudBees CI controller.

To add the Slack Bot Token as secret text:
  1. From your CloudBees CI controller, navigate to Manage Jenkins > CloudBees Slack Integration.

  2. Select Settings.

  3. Under Slack, to the right of Token, paste the token you copied when Installing the new Slack App in a client workspace.

  4. Select Save.

The CloudBees Slack Integration Plugin is greatly enhanced when it can gather information from other plugins including:

After you have set up CloudBees CI Slack Integration in the Slack App API and CloudBees CI, you need to configure users so that they can start receiving messages.