Discord app

The MergeHarbor app for Discord does what the Slack app 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 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.
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:

/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. 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.

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”.