# Discord app

> Ask MergeHarbor about pull requests in Discord with /mergeharbor, get review summaries and open fix pull requests: setup, permissions, commands, linking, alerts and troubleshooting.

The MergeHarbor app for Discord does what the [Slack app](https://mergeharbor.com/docs/slack) does: it answers questions about pull requests, summarises reviews, explains findings, opens a fix pull request after someone allowed confirms it, and posts review alerts with buttons. In Discord you use it with the `/mergeharbor` slash command. If you only want alerts in a channel, a [channel webhook](#alerts) is simpler and needs no app.

## Before you begin

- You need the **`settings.manage`** permission in MergeHarbor and **Manage Server** on the Discord server.
- Finish the setup in the same browser where you are signed in to MergeHarbor. MergeHarbor checks that the person who comes back from Discord is the person who started.
- A Discord server can be connected to one MergeHarbor organization at a time.

## Add the app to a server

1. In the console, open **Integrations → Discord** and choose **Add to Discord**.
2. Discord asks which server to add MergeHarbor to and shows the permissions it needs. Choose the server, then **Authorize**.
3. You return to the console with the server connected. The `/mergeharbor` command is available in the server straight away.
4. In the console, map channels to repositories and give each mapping a role. See [Channels, roles and caps](#channels-roles-and-caps).
5. Optional: run `/mergeharbor status` in a channel to check what MergeHarbor may do there, and ask your team to run `/mergeharbor link`.

If someone added the bot to a server another way, the first `/mergeharbor` command there replies with a **Connect to MergeHarbor** button that only the person who ran it sees. Someone with `settings.manage` opens it while signed in to MergeHarbor to connect the server. The link works for seven days.

## What MergeHarbor can access

MergeHarbor asks Discord for as little as it can.

| Permission               | Why                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------- |
| View Channels            | To list your channels so you can pick them for alerts and mappings                      |
| Send Messages            | To post alerts and fix pull request results                                             |
| Embed Links              | Answers and alerts are embeds with a **View in MergeHarbor** link                       |
| Read Message History     | Lets the bot edit its own messages, for example an alert after someone presses a button |
| Use Application Commands | The `/mergeharbor` command                                                              |

What MergeHarbor receives:

- The `/mergeharbor` commands people type and the buttons they press on MergeHarbor's messages, with the Discord user id, display name and channel.
- The server's channel names and whether `@everyone` can see each one, when you open the channel list in the console.

What it does not receive: any other message in your server, member lists, presence, or anyone's email address. The app needs no privileged intents.

To keep the bot out of a channel, deny it **View Channels** in that channel's permissions in Discord.

## Commands

`pr` is a pull request link, or `owner/repo#12`.

| Command                                      | MergeHarbor answers with                                                         | Who sees it | Credits |
| -------------------------------------------- | -------------------------------------------------------------------------------- | ----------- | ------- |
| `/mergeharbor summarise pr:<link>`           | The stored review summary, confidence, counts and findings                       | Channel     | None    |
| `/mergeharbor explain pr:<link> finding:2`   | One finding with its suggested change                                            | Channel     | None    |
| `/mergeharbor status pr:<link>`              | Pull request state, review status, open findings and the latest fix pull request | Channel     | None    |
| `/mergeharbor status`                        | The server, whether your account is linked, and what MergeHarbor may do here     | Only you    | None    |
| `/mergeharbor fix pr:<link>`                 | A confirmation with **Open fix pull request** and **Cancel**                     | Channel     | None    |
| `/mergeharbor ask pr:<link> question:<text>` | An answer from the same engine as **Ask** in the console                         | Channel     | Yes     |
| `/mergeharbor link`                          | A one-time link to link your Discord account                                     | Only you    | None    |
| `/mergeharbor help`                          | What the app can do                                                              | Only you    | None    |

Examples:

```text
/mergeharbor summarise pr:https://github.com/acme/shop/pull/412
/mergeharbor explain pr:acme/shop#412 finding:3
/mergeharbor ask pr:acme/shop#412 question:Does this change the retry behaviour of the payment client?
```

Discord shows "MergeHarbor is thinking…" while the answer is prepared. Answers say whether credits were used and have a **View in MergeHarbor** button. Questions and answers also appear on the pull request in the console.

### Buttons

| Button                    | Who can use it                                                                                       | What it does                                                       |
| ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Explain**               | Anyone, where MergeHarbor may answer about the repository                                            | Posts the review's summary and findings                            |
| **Open fix PR**           | Linked people in channels with the **fix** or **approver** role                                      | Asks for confirmation                                              |
| **Open fix pull request** | In **fix** channels, the pull request's author or an approver; in **approver** channels, an approver | Opens the fix pull request and updates the message with the result |
| **Cancel**                | Anyone                                                                                               | Cancels the fix pull request                                       |
| **Mute repo 24h**         | Linked people                                                                                        | Stops alerts for that repository in that channel for 24 hours      |

When someone who is not allowed presses a button, only they see the reason.

## Why slash commands, not mentions or direct messages

To read `@MergeHarbor` mentions or direct messages, a bot has to stay connected to Discord all the time and, for message text, be allowed to read message content in your server. With slash commands MergeHarbor needs neither: it only receives what people send to it on purpose and never sees any other message. The trade-off:

- Type `/mergeharbor ask` instead of mentioning the bot.
- Commands work in server channels, not in direct messages with the bot.
- Alerts go to channels, never to people's direct messages.

## Link your account

Discord does not share email addresses with apps, so each person links their account once:

1. Run `/mergeharbor link`. Only you see the reply.
2. Open the link within 15 minutes. Discord asks you to let MergeHarbor read your username and email address.
3. If your Discord email is verified and belongs to a member of the organization, your account is linked. Otherwise you land on a MergeHarbor page: sign in and confirm.

Open the link in a browser where you are signed in to Discord as the same account that ran the command; a link opened as another Discord account is refused. MergeHarbor reads your Discord user once, then revokes Discord's access token straight away.

People who are not linked get read-only answers: they can ask, summarise and explain, but cannot open fix pull requests or mute alerts.

## Channels, roles and caps

These work as in Slack:

- **Mappings** give a channel a set of repositories and a role: **ask**, **fix** or **approver**. The most specific mapping wins. See [Channels, repositories and roles](https://mergeharbor.com/docs/slack#channels-repositories-and-roles). To copy a channel ID, turn on **Developer Mode** in Discord's **Advanced** settings, then right-click the channel and choose **Copy Channel ID**.
- **Private repositories.** Discord does not tell MergeHarbor, when a command arrives, whether the channel is hidden. MergeHarbor therefore treats it as public (the safer choice) unless it is a private thread. To use a private repository in a channel, map that channel to the repository by its ID.
- **Credit caps** per channel and per person, each calendar month.
- **Activity log** with filters and CSV export. It records who did what, never message text.

## Alerts

Set up alerts under **Settings → Alerts & webhooks**, then add a rule that chooses what to send. Two Discord destinations are available:

| Destination           | Setup                                                                                                                                                                                                | Buttons |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Discord (app)**     | Pick a connected server, then one channel or every channel mapped to the pull request's repository                                                                                                   | Yes     |
| **Discord (webhook)** | In Discord, open the channel's settings, choose **Integrations → Webhooks → New Webhook**, and copy the webhook URL. Paste it in MergeHarbor. It must start with `https://discord.com/api/webhooks/` | No      |

Alerts never ping `@everyone`, `@here`, roles or people. Webhook URLs are encrypted and never shown again in full.

MergeHarbor can also post here when a PagerDuty incident starts. See [PagerDuty](https://mergeharbor.com/docs/pagerduty#suspect-pull-requests-when-an-incident-starts).

## Remove the app

1. In the console, open **Integrations → Discord** and choose **Disconnect** on the server.
2. In Discord, open **Server Settings → Integrations** and remove MergeHarbor.

If you only remove the bot in Discord, MergeHarbor disconnects the server the next time it tries to list its channels. Mappings and links are kept in case you connect the server again.

## Limits

| What                      | Limit                   |
| ------------------------- | ----------------------- |
| Organizations per server  | 1                       |
| `/mergeharbor link` link  | 15 minutes, used once   |
| Connect link for a server | 7 days                  |
| Question length           | 1,500 characters        |
| Mute                      | 24 hours per repository |
| Where commands work       | Server channels         |

## Troubleshooting

| Problem                                                                          | What to do                                                                                                                              |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| You return to the console with "sign in … as the person who started the install" | Start again from **Add to Discord** and finish in the same browser, signed in to MergeHarbor                                            |
| "This Discord server is connected to another organization"                       | Disconnect it in the other MergeHarbor organization first                                                                               |
| `/mergeharbor` does not appear in the server                                     | Add the app again from the console, which registers the command again. Check that your role may use application commands in the channel |
| `/mergeharbor` replies with **Connect to MergeHarbor**                           | The bot was added outside the console. Someone with `settings.manage` opens the link within seven days                                  |
| MergeHarbor will not answer about a repository                                   | Map the channel to the repository. For a private repository, map the channel by its ID                                                  |
| **Open fix PR** is refused                                                       | Link your account, and check the channel's role is **fix** or **approver**                                                              |
| Alerts to a channel do not arrive                                                | Check the bot can **View Channels** and **Send Messages** there, and that a rule sends events to the destination                        |
| Linking says you are signed in as a different account                            | Sign in to Discord in your browser as the account that ran the command, then run `/mergeharbor link` again                              |

## FAQ

**Does MergeHarbor read our server's messages?** No. It receives only the commands and button presses addressed to it.

**Does Discord share our email addresses?** Only with the person's consent, once, when they open their own link from `/mergeharbor link`. MergeHarbor does not keep Discord's access token.

**Can several organizations use one server?** No. A server is connected to one MergeHarbor organization at a time.

**Which commands use credits?** Only `/mergeharbor ask`. The others read what MergeHarbor already stored.

## Data handling

- **Verified requests.** Every command and button press from Discord is signed. MergeHarbor checks the signature and rejects requests older than five minutes. Replies go only to `discord.com`.
- **Redaction.** Command text is redacted of secrets before it is queued, and the queued copy, including Discord's short-lived reply token, is cleared once handled. Everything the app posts is redacted, with mentions turned off.
- **What is stored.** Per channel, the pull request a conversation is about and a short redacted memory, kept for 90 days after the last answer; the activity log, with no message text, for 400 days. Questions and answers are kept on the pull request like console questions.

## Self-hosted installations

Self-hosted installations create their own Discord application and set `DISCORD_APP_ID`, `DISCORD_PUBLIC_KEY`, `DISCORD_BOT_TOKEN` and `DISCORD_CLIENT_SECRET`. Steps are in `docs/integrations/DISCORD.md` and in `docs/OAUTH_APPS.md` under "Discord app".