Slack integration

Note

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

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.

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' => [
         'token' => 'xoxb-3875744143189-3925283455653-pxxZoTKz3JqUeDXGd66XFW4D',  
         'project_channels' => [
              // Project myproject will go into slack channel myproject-channel
              'myproject' => [
                  'myproject-channel',
               ],
              // Project with no setting will go to no-project-channel
              '*no-project-channel* => [
                  'no-project-channel',
               ],
              // No project on this review/change. 
              '*without_project*' => [
                   'no-link-project',  
               ],
               //All notification get sent here even if we matched above.
               '*all*' => [
                    '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 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