Skip to content

Commit c75789d

Browse files
danciaclaradanciaclara
committed
Added Slack integration config
1 parent 5c5a6fa commit c75789d

File tree

2 files changed

+283
-1
lines changed

2 files changed

+283
-1
lines changed

‎mint.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,8 @@
9393
{
9494
"group": "Integrations",
9595
"pages": [
96-
"self-hosting/govern/integrations/github"
96+
"self-hosting/govern/integrations/github",
97+
"self-hosting/govern/integrations/slack"
9798
]
9899
},
99100
"self-hosting/govern/reverse-proxy",

‎self-hosting/govern/integrations/slack.mdx‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
---
2+
title : Configure Slack App for Plane integration
3+
sidebarTitle: Slack
4+
---
5+
6+
<Warning>
7+
**Activate Slack integration**
8+
9+
After creating and configuring the Slack app and configuring the instance as detailed on this page, you'll need to [set up the Slack integration](https://docs.plane.so/integrations/slack) within Plane.
10+
</Warning>
11+
12+
## Create Slack App
13+
14+
To configure Slack integration, you'll need to create a Slack App within your organization. Follow these steps:
15+
16+
1. Go to [Your Apps](https://api.slack.com/apps) on Slack.
17+
18+
2. Click **Create New App**.
19+
20+
3. Choose **From a manifest** (this is the easiest way to set up your app).
21+
22+
4. Select the workspace where you want the app installed.
23+
24+
5. Remove the default manifest and paste the one below, making sure to update the placeholders with your actual values.
25+
<Tabs>
26+
<Tab title="JSON">
27+
```json
28+
{
29+
"display_information": {
30+
"name": "[YOUR_APP_NAME]",
31+
"description": "[YOUR_APP_DESCRIPTION]",
32+
"background_color": "#224dab"
33+
},
34+
"features": {
35+
"bot_user": {
36+
"display_name": "[YOUR_APP_NAME]",
37+
"always_online": false
38+
},
39+
"shortcuts": [
40+
{
41+
"name": "Create new issue",
42+
"type": "message",
43+
"callback_id": "create_new_issue",
44+
"description": "Create a new issue in plane"
45+
}
46+
],
47+
"slash_commands": [
48+
{
49+
"command": "/plane",
50+
"url": "https://[YOUR_DOMAIN]silo/api/slack/command/",
51+
"description": "Create issue in Plane",
52+
"should_escape": false
53+
}
54+
],
55+
"unfurl_domains": [
56+
"[YOUR_DOMAIN]"
57+
]
58+
},
59+
"oauth_config": {
60+
"redirect_urls": [
61+
"https://[YOUR_DOMAIN]silo/api/slack/team/auth/callback/",
62+
"https://[YOUR_DOMAIN]silo/api/slack/user/auth/callback/"
63+
],
64+
"scopes": {
65+
"user": [
66+
"chat:write",
67+
"identify",
68+
"im:read",
69+
"im:write",
70+
"links:write",
71+
"links:read"
72+
],
73+
"bot": [
74+
"channels:join",
75+
"channels:read",
76+
"users:read",
77+
"users:read.email",
78+
"chat:write",
79+
"chat:write.customize",
80+
"channels:history",
81+
"groups:history",
82+
"mpim:history",
83+
"im:history",
84+
"links:read",
85+
"links:write",
86+
"groups:read",
87+
"im:read",
88+
"mpim:read",
89+
"reactions:read",
90+
"reactions:write",
91+
"files:read",
92+
"files:write",
93+
"im:write",
94+
"commands"
95+
]
96+
}
97+
},
98+
"settings": {
99+
"event_subscriptions": {
100+
"request_url": "https://[YOUR_DOMAIN]silo/api/slack/events",
101+
"bot_events": [
102+
"link_shared",
103+
"message.channels",
104+
"message.im"
105+
]
106+
},
107+
"interactivity": {
108+
"is_enabled": true,
109+
"request_url": "https://[YOUR_DOMAIN]silo/api/slack/action/",
110+
"message_menu_options_url": "https://[YOUR_DOMAIN]silo/api/slack/options/"
111+
},
112+
"org_deploy_enabled": false,
113+
"socket_mode_enabled": false,
114+
"token_rotation_enabled": true
115+
}
116+
}
117+
```
118+
119+
</Tab>
120+
<Tab title="YAML">
121+
```yaml
122+
display_information:
123+
name: [YOUR_APP_NAME]
124+
description: [YOUR_APP_DESCRIPTION]
125+
background_color: "#224dab"
126+
features:
127+
bot_user:
128+
display_name: [YOUR_APP_NAME]
129+
always_online: false
130+
shortcuts:
131+
- name: Create new issue
132+
type: message
133+
callback_id: create_new_issue
134+
description: Create a new issue in plane
135+
slash_commands:
136+
- command: /plane
137+
url: https://[YOUR_DOMAIN]silo/api/slack/command/
138+
description: Create issue in Plane
139+
should_escape: false
140+
unfurl_domains:
141+
- [YOUR_DOMAIN]
142+
oauth_config:
143+
redirect_urls:
144+
- https://[YOUR_DOMAIN]silo/api/slack/team/auth/callback/
145+
- https://[YOUR_DOMAIN]silo/api/slack/user/auth/callback/
146+
scopes:
147+
user:
148+
- chat:write
149+
- identify
150+
- im:read
151+
- im:write
152+
- links:write
153+
- links:read
154+
bot:
155+
- channels:join
156+
- channels:read
157+
- users:read
158+
- users:read.email
159+
- chat:write
160+
- chat:write.customize
161+
- channels:history
162+
- groups:history
163+
- mpim:history
164+
- im:history
165+
- links:read
166+
- links:write
167+
- groups:read
168+
- im:read
169+
- mpim:read
170+
- reactions:read
171+
- reactions:write
172+
- files:read
173+
- files:write
174+
- im:write
175+
- commands
176+
settings:
177+
event_subscriptions:
178+
request_url: https://[YOUR_DOMAIN]silo/api/slack/events
179+
bot_events:
180+
- link_shared
181+
- message.channels
182+
- message.im
183+
interactivity:
184+
is_enabled: true
185+
request_url: https://[YOUR_DOMAIN]silo/api/slack/action/
186+
message_menu_options_url: https://[YOUR_DOMAIN]silo/api/slack/options/
187+
org_deploy_enabled: false
188+
socket_mode_enabled: false
189+
token_rotation_enabled: true
190+
```
191+
</Tab>
192+
</Tabs>
193+
194+
6. Review the permissions and click **Create**.
195+
196+
### Manifest reference
197+
198+
The manifest file defines the configuration for integrating Plane with Slack. It requests access to several features, enabling Plane to interact with Slack efficiently.
199+
200+
#### Features
201+
202+
| Feature | Explanation |
203+
| --- | --- |
204+
| `bot_user` | Required to send thread messages while syncing issues or sending Plane notifications to Slack.|
205+
| `slack_commands` | A Slack command (`/plane`) allows users to create issues directly from Slack using a slash command. |
206+
| `shortcuts` | After activation, users can create issues from messages inside Slack.|
207+
| `unfurl_domain` | Specifies the domain where Plane is hosted. When an issue, cycle, or module link is pasted in Slack, it generates a preview of the entity. |
208+
209+
#### Variables
210+
211+
|Variable|Explanation|
212+
|------------|--------|
213+
|`YOUR_DOMAIN`|The domain where Plane is hosted. This is required for sending webhook events and authentication callbacks.|
214+
|`YOUR_APP_NAME`|The name you want to give your Slack app. "Plane" is a good default option.|
215+
|`YOUR_APP_DESCRIPTION`|A short description of your Slack app’s purpose.|
216+
217+
#### Event subscription
218+
219+
For thread sync and link unfurling to work, event subscriptions must be enabled. These events send relevant activity to Plane.
220+
221+
| Bot event | Explanation |
222+
| --- | --- |
223+
| `link_shared` | When a link is shared in Slack and its hostname matches `unfurl_domain`, Plane receives the event and generates a preview of the entity. |
224+
| `message_channels` | When a message is posted in a channel, an event is triggered in Plane to support thread sync. |
225+
| `message_im` | When a direct message (DM) is posted, an event is triggered in Plane to support thread sync. |
226+
227+
#### User permissions
228+
229+
| Permission | Explanation |
230+
| --- | --- |
231+
| `chat:write` | Allows the bot to send messages in channels and conversations it is a member of. |
232+
| `identify` | Allows the bot to verify its own identity and retrieve basic information. |
233+
| `im:read` | Enables the bot to view direct messages (DMs) where it has been added. |
234+
| `im:write` | Allows the bot to send direct messages (DMs) to users. |
235+
| `links:write` | Permits the bot to add, edit, and remove link unfurls. |
236+
| `links:read` | Allows the bot to view link unfurls and associated metadata. |
237+
238+
#### Bot permissions
239+
240+
| Permission | Explanation |
241+
| --- | --- |
242+
| `channels:join` | Allows the bot to join public channels. |
243+
| `channels:read` | Permits viewing public channel information and members. |
244+
| `users:read` | Allows viewing user information and presence status. |
245+
| `users:read.email` | Enables access to users' email addresses. |
246+
| `chat:write` | Allows sending messages in channels and conversations. |
247+
| `chat:write.customize` | Enables customization of the bot's name and profile when sending messages. |
248+
| `channels:history` | Allows viewing message history in public channels. |
249+
| `groups:history` | Permits viewing message history in private channels. |
250+
| `mpim:history` | Enables access to message history in multi-person direct messages. |
251+
| `im:history` | Allows viewing message history in direct messages. |
252+
| `links:read` | Permits viewing link unfurls and associated metadata. |
253+
| `links:write` | Allows adding, editing, and removing link unfurls. |
254+
| `groups:read` | Enables viewing private channel information and members. |
255+
| `im:read` | Allows viewing direct messages where the bot is added. |
256+
| `mpim:read` | Permits viewing multi-person direct messages. |
257+
| `reactions:read` | Enables viewing emoji reactions on messages. |
258+
| `reactions:write` | Allows adding and removing emoji reactions. |
259+
| `files:read` | Permits viewing and downloading files. |
260+
| `files:write` | Enables uploading, editing, and deleting files. |
261+
| `im:write` | Allows sending direct messages to users. |
262+
| `commands` | Enables the bot to add and respond to slash commands. |
263+
264+
## Configure Plane instance
265+
After creating your Slack app, follow these steps:
266+
267+
1. Go to the **Event Subscriptions** tab.
268+
269+
2. Click **Retry** to verify your event subscription URL.
270+
271+
3. Navigate to the **Basic Information** tab on Slack to find your `client_id` and `client_secret`.
272+
273+
4. Add these environment variables with the values to your Plane instance's `.env` file.
274+
```bash
275+
SLACK_CLIENT_ID=<your_client_id>
276+
SLACK_CLIENT_SECRET=<your_client_secret>
277+
```
278+
279+
280+
281+

0 commit comments

Comments
 (0)