Skip to content

slack.md

Latest commit

 

History

History
128 lines (109 loc) · 5.23 KB

slack.md

File metadata and controls

128 lines (109 loc) · 5.23 KB

Integration with Slack

CodeStream's Slack integration allows for sharing codemark comments inside Slack channels. Once a CodeStream user completes the OAuth process with Slack and receives their access token, they are able to cross-post their CodeStream codemarks & replies to Slack.

From within a Slack channel, those cross-posted messages use Slack's Interactive Components App feature to allow Slack users to send replies back to CodeStream. Since this feature allows for only one callback URL per app, a dedicated CodeStream Slack App for each CodeStream environment is required.

With the Slack v3 implementation, users can reply to messages in Slack threads and have those messages be synchronized back to CodeStream. This uses Slack's Events API, which requires a single URL be configured per Slack App.

All requests made by slack are signed and verified using Slack's procedure for doing so.

Create the Slack App

Steps to create a Slack App for a non-production CodeStream environment.

  1. Create a Slack App for connecting to CodeStream with the following settings.

    • Go to https://api.slack.com/apps, make sure you're logged in to your workspace with administrative privileges, and press Create New App. We recommend naming it CodeStream <environment>.
    • Select the OAuth & Permissions feature, make these settings and save them.
      • Add the following Redirect URL:
        • https://<codestream-api-host>/no-auth/provider-token/slack
      • Add the following Bot Token Scopes and save them (Request reasons included here). NOTE: the source of truth for the list of scopes is here. You should verify this list accordingly.
        • channels:history - We receive message events for messages posted to public channels the bot has access to.
        • channels:read - We fetch information about public channels the bot has access to.
        • chat:write - We post messages to watched threads as the bot on behalf of users.
        • groups:history - We receive message events for messages posted to public channels the bot has access to.
        • groups:read - We fetch information about private channels the bot has access to.
        • mpim:history - We receive message events for messages posted to group DMs the bot has access to.
        • mpim:read - We fetch information about group DMs the bot has access to.
        • users:read - We fetch information about users.
        • users:read.email - We try to correlate CodeStream accounts with Slack accounts via e-mail.
      • Add the following User Token Scopes and save them (Request reasons included here). NOTE: the source of truth for the list of scopes is here. You should verify this list accordingly.
        • channels:read - We allow users to select a public channel to share to.
        • channels:write - We allow users to invite the CodeStream bot to public channels.
        • chat:write - Users can send a copy of their messages from CodeStream to slack.
        • groups:read - We allow users to select a private channel to share to.
        • groups:write - We allow users to invite the CodeStream bot to private channels.
        • im:read - We allow users to select a direct message to share to.
        • mpim:read - We allow users to select a group DM to share to.
        • mpim:write - We allow users to create group DMs to share to.
        • users.profile:write - We can update your slack status to reflect your current work.
        • users:read - We show the list of users.
        • users:read.email - We try to correlate CodeStream accounts with slack accounts via e-mail.
    • Select the Interactivity & Shortcuts section, make these settings and save them.
      • Turn on Interactivity (the switch on the upper right)
      • Add the following Request URL:
        • https://<codestream-api-host>/no-auth/provider-action/slack
    • Select the Event Subscriptions section and do the following then save them.
      • Enable events (on)
      • Set the Request URL to https://<codestream-api-host>/no-auth/provider-action/slack-events (note the server needs to be running to respond to this request when you configure it)
      • In the Subscribe to Bot Events section, add these bot user events:
        • message.channels
        • message.groups
        • message.mpim

Add and/or Distribute Slack App

Add and/or distribute the Slack App as needed. It will need to be added to any workspaces that wish to connect with the corresponding CodeStream environment.

Update the CodeStream Configuration

Finally, add the secrets and configuration data to the CodeStream API server's configuration file in the integrations section.

From the Basic Information page of the Slack App, get these data and add them to the CodeStream configuration file.

  • App ID
  • Client ID
  • Client Secret
  • Signing Secret
{
	"integrations": {
		"slack": {
			"cloud": {
				"appClientId": null,
				"appClientSecret": null,
				"appId": null,
				"appSigningSecret": null,
				"disabled": false,
				"interactiveComponentsEnabled": true
			}
		}
	}
}

Permalink to Code Requesting Auth

This is the source of truth where slack access is concerned.