CodeHerderSearch⌘KRequest access →

Setting up the Slack app

Create your own Slack app from the shipped manifest, set three environment variables, then connect Slack.

CodeHerder posts task events to Slack channels. The Slack app makes this possible. A self-hosted server runs its own Slack app. This page covers the app setup. Posting task events to Slack covers everything after it.

Why you run your own app

Slack fixes the OAuth redirect URL of an app to one domain. The hosted CodeHerder app redirects to the hosted server. A self-hosted server has a different domain, so it cannot use that app. The signing secret also belongs to one app. Your bot token and your events stay on your own server.

Create the app

  1. Open the Slack app page and choose Create New App.
  2. Choose From a manifest, then pick the Slack workspace that owns the app.
  3. Paste this manifest. It already holds the URLs of your server.
display_information:
  name: CodeHerder
  description: Posts CodeHerder task events to Slack channels.
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: CodeHerder
    always_online: false
oauth_config:
  redirect_urls:
    - https://api.codeherder.com/v1/oauth-callback
    - https://api.codeherder.com/v1/slack/link/callback
  scopes:
    bot:
      - chat:write
      - channels:read
      - groups:read
      - im:write
      - channels:history
      - groups:history
      - im:history
      - commands
      - app_mentions:read
      - files:write
      - reactions:write
      - links:read
      - links:write
      - users:read
    user:
      - openid
settings:
  interactivity:
    is_enabled: true
    request_url: https://api.codeherder.com/v1/slack/interactions
  event_subscriptions:
    request_url: https://api.codeherder.com/v1/slack/events
    bot_events:
      - app_uninstalled
      - tokens_revoked
      - message.channels
      - message.groups
      - message.im
      - app_mention
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

The manifest asks for the history scopes and the message events. They let CodeHerder read replies in task threads. It also sets the Interactivity URL, which the Approve, Reject, Answer and Unblock buttons need.

Slack checks the events URL when you save. The check fails until the server knows the signing secret. If it fails, finish the next two sections first. Then open Event Subscriptions and retry the URL.

Update an existing app

An app made before threads and replies lacks some scopes and events. Delivery keeps working without them. Threads and replies stay off until you add them.

The new bot scopes are im:write, channels:history, groups:history and im:history. The new bot events are message.channels, message.groups and message.im.

The manifest also asks for scopes that no feature needs yet: commands, app_mentions:read, files:write, reactions:write, links:read, links:write and users:read. It subscribes to app_mention and turns on the App Home messages tab, so people can write to the bot in a direct message. They are there now so a later feature does not need another reinstall. After you save the manifest, reinstall through CodeHerder’s Slack page (Connect or Reinstall), not Slack’s reinstall banner. CodeHerder then stores the new token and scopes.

  1. Open your app in Slack and choose App Manifest.
  2. Paste the manifest from Create the app, or add the scopes and events by hand. Save it.
  3. Open the Slack page in CodeHerder and press Reinstall Slack. Approve the new scopes in Slack.

The prompt on the Slack page goes away once the installation holds every new scope.

Turn on distribution

Skip this step when one Slack workspace installs the app. When several Slack workspaces install it, open Manage Distribution and choose Activate Public Distribution.

Set the credentials

Open Basic Information and copy three values. Set them in the server environment.

Slack value Variable
Client ID CH_SLACK_CLIENT_ID
Client Secret CH_SLACK_CLIENT_SECRET
Signing Secret CH_SLACK_SIGNING_SECRET

All three are required. Restart the server after you set them. When one is missing, the Connect button on the Slack page is disabled. The page gives the reason and links to this page.

Connect Slack and add routes

Once the server has the three values, connect Slack, invite the bot and add routes as described in Posting task events to Slack.

Add thread replies to an existing app

An app made from an older manifest lacks the history scopes and message events. Its connection posts one message per event, with no task thread. To update it:

  1. Open the app in Slack. Under OAuth and Permissions, add the scopes from the manifest above. Under Event Subscriptions, add the message events.
  2. In CodeHerder, open the Slack page. Click Edit connection, click Disconnect, then connect again. Approve the new permissions in Slack.

Your routes stay as they were. See Turn on threads and replies.

Buttons

The Approve, Reject, Answer and Unblock buttons are on by default. They need the Interactivity URL from the manifest and the signing secret. To turn them off, set CH_SLACK_INTERACTIVITY to false and restart the server. Messages then post with no buttons. Each member also links a Slack account before a button acts for them. See Act from Slack.

Troubleshooting

  • A route is off, or the connection is off. See Posting task events to Slack.
  • Connect answers oauth_app_not_configured. One of the three variables is empty. Set it and restart.
  • Messages have no Approve, Reject or Answer buttons. Check that CH_SLACK_INTERACTIVITY is not false. Check that the Interactivity URL in the Slack app matches the manifest.
  • Slack events fail with invalid_signature. The signing secret is wrong, or the server clock is more than five minutes off.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close