Slack integration

Note

  • You must be an admin or super user to integrate Helix Swarm with Slack.

  • Slack integration only supports the Swarm project names in lower case letters in the config.php file. For example, myproject.

This section details how to install, configure, and use the Helix Swarm Slack integration. The Helix Swarm Slack integration lets teams collaborate with Helix Swarm notifications in Slack. The Slack integration posts a message in the configured Swarm project Slack channels each time a change is committed, a review is created, or a review is updated in the project.

To install the Slack integration:

  1. Navigate to https://www.perforce.com/products/helix-swarm/slack-integration.

  2. Click Add to Slack button.

  3. Select the workspace from the top of the page that you wish to integrate Slack with.

  4. Request install permissions from your Application Manager.

  5. Once the Application Manager approves your request, Helix Swarm Slack integration is installed into your selected workspace.

  6. To enable Swarm to work with Slack, edit the Swarm config.php file to include the displayed Slack configuration.

    The Swarm config.php file is saved in the SWARM_ROOT/data/ directory.

Note

After the Helix Swarm Slack integration is installed, you must configure the project in the Swarm config.php file. For more information on how to configure a project for Slack integration, see Setup project configurations.

Slack configuration

Add the following Slack configuration to the Swarm config.php file. The Swarm config.php file is saved in the SWARM_ROOT/data/ directory.

'slack' => array(
	     'token' => 'TOKEN',
	     'project_channels' => array(), //See Setup project configurations to configure a project for Slack integration
	     'summary_file_names' => false,
	     'bypass_restricted_changelist' => false,
	     'summary_file_limit' => 10,
	     'user' => array(
		        'enabled' => true,
		        'name' =>'Helix Swarm',
		        'icon' => 'URL',
		        'force_user_header' => false,
		),
),

token

The Slack app provides a token that is used by Swarm.

project_channels

Specifies the Swarm projects and Slack channels they post to in the project_channels array. You can configure multiple channels to receive a notification for a project. For more information on how to use project_channels configurable, see Setup project configurations.

summary_file_names

Attaches the file to the original notification message sent to a Slack channel.

bypass_restricted_changelist

Allows Swarm to post notification messages to a Slack channel when a change is committed or a review is created for a restricted changelist, default value is false. For more information about a restricted changelist, see Restricted Changes.

summary_file_limit

Limits the number of files shown in the original notification message sent to a Slack channel, default value is 10.

user

Specifies details about the Swarm user in a Slack notification.

  • enabled: Forces the Swarm app to use the custom user name. This overrides the Swarm app details.

  • name: This is the user name shown in the Slack channel when a notification is posted.

  • icon: This is the avatar icon shown in the Slack channel when a notification is posted, overrides the avatar set in the Swarm app.

  • force_user_header: The Slack notification shows the user name and avatar only for the first notification by a user. Slack does not apply the user name and avatar to any more notifications from the same user. By default this is set to false.

    When set to true, Slack adds the user name and avatar for every notification.

Setup project configurations

This section details how you can configure a project in Helix Swarm to send Slack notifications to a Slack channel.

Important

After project configuration is complete, you must restart the workers and the configuration cache for the updated configuration to take effect.

  • For more information on how to restart workers, see Workers section.

  • For more information on how to restart configuration cache, see Reload Configuration button section.

Note

For private projects, ensure that the Slack channel you wish to send notifications to is a private channel.

To send notifications to a channel for a project, you must configure the project_channels block as follows:

<?php
    //This block should be a peer of 'p4' 
    'slack' => array(
         'token' => 'xoxb-3875744143189-3925283455653-pxxZoTKz3JqUeDXGd66XFW4D',  
         'project_channels' => array(
              //Project myproject will go into slack channel myproject-channel
              'myproject' => array( 
                  'myproject-channel',
               ),
              //Project with no setting will go to no-project-channel
              '*no-project-channel*' => array(
                  'no-project-channel',
               ),
              //No project on this review/change 
              '*without_project*' => array(
                   'no-link-project',  
               ),
               //All notification get sent here even if we matched above
               '*all*' => array(
                    'all-notifications', 
               ),
        ),
  ),

project_channels

Specify the Swarm projects and the Slack channels they post to in the project_channels array. You can configure multiple channels to receive a notification for a project.

Example

  • Swarm project: myproject

  • Slack channel: myproject-channel

All notifications for the project myproject will go to the myproject-channel Slack channel.

*no-project-channel* (optional)

For a project that has no defined project mapping and with *no-project-channel* configurable defined, the Slack notifications are sent to *no-project-channel*. For example, all notifications for the project myproject goes to myproject-channel and similarly all notifications for any other project goes to *no-project-channel*.

*without_project* (optional)

When *without_project* configurable is defined, it means that no notification is sent if the notification is not associated with a project.

*all* (optional)

When *all* configurable is defined, all notifications are sent here even if *no-project-channel* and *without_project* options are configured.

Swarm is now configured to send notifications to a Slack channel for a project.

Slack notification trigger

Helix Swarm will post a message on a Slack channel for every commit. This includes each time a change is committed, a review is created, or a review is updated. Any update to a review in Helix Swarm is displayed as a recently occurred activity stream in the associated Slack channel.

Here is a list of actions that will trigger Helix Swarm to send a notification to the associated project Slack channel.

Event Description
joined When a user joins the review
left When a user leaves the review
made their vote required on When a user's vote has been made required
made their vote optional on When a user's vote has been made optional
disabled notifications on When a user disables the notifications for a review
re-enabled notifications on When a user re-enables the notifications for a review
edited reviewers on When the reviewers are edited for a review
voted When a user votes up or down
cleared their vote on When a user clears their vote
requested further review of When a user changes the review state to needsReview
requested revisions to When a user changes the review state to needsRevision
rejected When a user changes the review state to rejected
archived When a user changes the review state to archived
approved When a user changes the review state to approved
updated description of When a user updates the description of the review
updated files in When a user updates the files in a review