Skip to content
OpenPerf
Esc
↑↓navigate↵open⌘Jpreview
On this page

Integrations

Create the Slack, Discord, Telegram, GitHub and Linear apps and set their keys.

A provider turns on only when INTEGRATIONS_ENCRYPTION_KEY and all of its own variables are set. Set them in api and worker-jobs, except Linear, which only api needs.

Provider Capability Variables
Slack Alert delivery SLACK_CLIENT_ID, SLACK_CLIENT_SECRET
Discord Alert delivery DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_BOT_TOKEN
Telegram Alert delivery TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_USERNAME, TELEGRAM_WEBHOOK_SECRET
GitHub Release commits, code links, blame GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
Linear Issues created from errors LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET

URLs below use https://api.example.com for your API_ORIGIN.

Encryption key

openssl rand -base64 32

Set the result as INTEGRATIONS_ENCRYPTION_KEY. It encrypts stored credentials and webhook secrets: never change it, or every connected integration and webhook stops working. Without it, integrations and webhooks are off.

Slack

  1. Create an app at api.slack.com/apps.
  2. Under OAuth & Permissions, add the redirect URL https://api.example.com/api/v1/integrations/slack/callback and the bot scope incoming-webhook.
  3. Set SLACK_CLIENT_ID and SLACK_CLIENT_SECRET.

Discord

  1. Create an application at discord.com/developers/applications and add a bot.
  2. Under OAuth2, add the redirect https://api.example.com/api/v1/integrations/discord/callback.
  3. Set DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET and DISCORD_BOT_TOKEN.

Telegram

  1. Create a bot with @BotFather. Set TELEGRAM_BOT_TOKEN, and TELEGRAM_BOT_USERNAME without the @.
  2. Set TELEGRAM_WEBHOOK_SECRET to 16 to 256 letters, digits, _ or -, for example openssl rand -hex 32.

worker-jobs registers the webhook https://api.example.com/api/v1/integrations/telegram/webhook when it starts. api rejects updates without the secret.

GitHub

  1. Create a GitHub App under your organization’s Developer settings.
  2. Set the callback URL and the setup URL to https://api.example.com/api/v1/integrations/github/callback. Turn on Request user authorization (OAuth) during installation.
  3. Grant read-only access to repository Contents and Metadata.
  4. Generate a private key. Set GITHUB_APP_ID, GITHUB_APP_SLUG (from github.com/apps/<slug>), GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET and GITHUB_APP_PRIVATE_KEY. The key may be on one line with \n for newlines.

Linear

  1. Create an OAuth application in Linear’s Settings → API.
  2. Add the callback URL https://api.example.com/api/v1/integrations/linear/callback.
  3. Set LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET in api.

Was this page helpful?