Slack integration

Integrating Buddy with Slack will keep your team updated with automatic notifications on finished builds and deployments to a Slack channel. You can also use it to trigger and get the status of your pipelines with slash commands.

Example pipeline with Slack notification

Types of integration

The integration can be performed in two ways:

1. Using the official Buddy Slack app (recommended).

   • can be installed in any Slack workspace
   • requires adding a 3rd-party app on on-premises installations to become available

2. Using a private Slack app.

   • restricted to Slack workspaces to which the app creator belongs
   • does not require a 3rd-party app on on-premises installations

Configuration

Buddy Slack app

1. Navigate to Integrations and click New integration.
2. Look up Slack on the service list:

Slack on the integrations list

3. Set the name and sharing scope. Leave the authorization method at Buddy Slack App:

Slack integration configuration

4. Authorize Buddy in the selected Slack workspace:

OAuth authorization screen

Private Slack app

This integration requires adding an OAuth token for a bot user that will send messages on behalf of Buddy. To do that, switch the type to Private Slack App and click the Get Token link. A box with installation instructions will appear:

Private Slack app install instructions

A. If you already have a Slack application, click Go to Slack's OAuth Apps, copy the Bot User OAuth Token, and paste it to Buddy:

Bot user OAuth token location

B. If you don't have the application, Buddy will help you create one.

1. Click the link in the box to open the Slack API apps page.
2. Click Generate Token and copy the Access Token:

App configuration token location

3. Paste the token to the input in Buddy and click Create private Slack App. This will automatically create an application with all required scopes and settings.
4. On the next screen, click Install private app in Slack and install the application to your workspace:

Installing app to Slack workspace

5. Copy the newly generated Bot User OAuth Token:

Bot user OAuth token location

6. Switch back to Buddy, close the box, and paste the token to the integration input:

Slack integration configuration

Sending messages

Adding the integration installs a messaging bot to your Slack workspace. The bot has no permissions to private channels and needs to be added manually.

1. Right-click on the desired channel and select View channel details.
2. Switch to the Integrations tab and click Add an App.
3. You should see Buddy in the list of apps installed in your Slack workspace. Click Add to activate it in your channel:

Adding Buddy app to the channel

4. Now that Buddy is allowed to send messages, you can add the Slack action to the pipeline:

Slack location in action roster

5. In the action details, select the channel where you installed the bot. You can customize the message to your liking using environment variables.

Slack message configuration screen

Slash commands

Slash commands are used for ChatOps interactions between Buddy and Slack. To use slash commands, you first need to configure a Slack application that binds the request URL of the pipeline with the desired command:

1. Add a new application via the Slack API panel.
2. Select From scratch configuration, enter the App Name (e.g. Buddy Slash Commands), and pick your Slack workspace.
3. Click Slash Commands in the features and functionality section.

4. Click Create New Command, fill in the mandatory fields, and save changes to continue. Repeat for all pipelines that you want to serve.

   • Command: the name of the command that will trigger the desired operation from Slack. The best idea is to set it to the name of the target pipeline, e.g. /prod-stage
   • Request URL: the unique Slack handle of the target pipeline
   • Short description: e.g. "Staging pipeline in Production"

Adding commands to app

Eventually, you should end up with a list like this:

Commands in slash commands app

5. When ready, go to Settings ➝ Install app and click Install to Workspace to activate the app in your Slack workspace.
6. The last step is adding the app to the Slack channel from which you want to run the commands – just like with the messaging bot.

Once done, you should see the app in the channel details:

Slack channel details with slash commands app

Slack handle location

The request URL – also known as Slack handle – is required to identify the pipeline in Buddy. It is unique to every pipeline and can be found in the dropdown options on the pipeline overview:

Slack handle location

Supported commands

The [name] parameter represents the name of the command in the Slack application.

Example: /prod-stage clear run 1c002dd – clears pipeline cache and runs deployment from revision 1c002dd in pipeline tied to /prod-stage command.

• /[name] status – displays pipeline status
• /[name] run – runs pipeline. Can be used with params. Can be used with any revision.
• /[name] approve – approves waiting pipeline
• /[name] params a=b c="some text" – passes parameters to another pipeline
• /[name] cancel – cancels pipeline execution (must be in progress)
• /[name] refresh – runs pipeline from scratch. Can be used with any revision.
• /[name] retry – runs execution again (must be terminated or canceled)
• /[name] clear run – clears pipeline cache. Can be used with run and refresh. Can be used with any revision.

For wildcard pipelines, you can send branch, tag, and pull request parameters:

• /[name] clear run tag=1.1
• /[name] clear run branch=dev
• /[name] clear run pullRequest=feature-update