Skip to main content
This guide connects your self-hosted instance to a Slack workspace, so people can mention @Compiler with a question and get the answer in the thread. You create a Slack app of your own and give Compiler its credentials in Settings > Slack. Nothing goes in environment variables, and nothing needs a restart.

​
Prerequisites

  • You’re an owner or admin of your Compiler organization.
  • You can create apps in your Slack workspace. Some workspaces need an admin to approve a new app.
  • PUBLIC_URL is set to the address your instance is reached on, such as https://compiler.yourdomain.com. Slack sends questions to that address, so it has to be reachable from the internet over HTTPS. The Slack page in settings tells you if it’s missing.

​
Step 1: Create the Slack app

  1. In Compiler, open Settings > Slack.
  2. Click Create the Slack app. Slack opens with a manifest already filled in, pointing at your instance.
  3. Choose your workspace and create the app.
If the button doesn’t suit you, click Copy the manifest instead, go to api.slack.com/apps, choose Create New App > From a manifest, and paste it. The manifest asks for these permissions and no more: The manifest also turns on Slack’s agent features for the app. It appears under Agents in the Slack sidebar with a split-view pane and suggested prompts, shows a “working” indicator with a Stop button while it answers, and streams its reply.
Slack doesn’t let workspace guests use agent-enabled apps.
Compiler only acts on messages in threads it has already answered in. Other channel messages are acknowledged and dropped.

​
Step 2: Give Compiler the credentials

In your new Slack app, open Basic Information and find App Credentials. Copy these three into Settings > Slack in Compiler and save: Both secrets are stored encrypted and are never shown again. To change them later, click Replace credentials.

​
Step 3: Let Slack verify the address

Slack only sends events to an address it has verified, and it couldn’t verify yours before Compiler had the Signing Secret.
  1. In your Slack app, open Event Subscriptions.
  2. Next to the Request URL, click Retry. It should change to Verified.
  3. Save the page if Slack asks you to.
If it doesn’t verify, check that PUBLIC_URL is right and that https://your-instance/api/slack/events is reachable from the internet.

​
Step 4: Add Compiler to your workspace

Back in Settings > Slack, click Add to Slack, choose the workspace and approve.
Do this from Compiler, not with the Install to Workspace button on the app’s page at api.slack.com. That button installs the app without telling Compiler, and questions from the workspace are then dropped.
The page now shows the connected workspace. Invite the bot to a channel with /invite @Compiler, or message it directly.

​
Optional: add an icon

A manifest can’t carry an icon, so the app starts with Slack’s placeholder. To give it one, open the app’s Basic Information, scroll to Display Information and upload an image.

​
Who can ask, and what they can see

Anyone in the connected workspace can ask a question. Questions from Slack are asked by a Compiler account that belongs to your organization, called Compiler for Slack, so an answer can draw on every project in the organization, whoever asked. Each answer links to the full conversation in Compiler. Opening that link needs a Compiler login in your organization.

​
Disconnect

Click Disconnect in Settings > Slack. Compiler removes itself from the workspace. Conversations it already had stay in Compiler, and links to them keep working. You can then remove the credentials as well, or leave them in place to reconnect later.

​
Update an existing app

When a new version of Compiler asks for more permissions, the manifest changes. Open the app’s App Manifest page at api.slack.com, replace it with the manifest from Settings > Slack, save, then click Add to Slack in Compiler again to approve the new permissions. Nothing else needs redoing.