Slack app

The MergeHarbor Slack app answers questions about pull requests in Slack, summarises reviews, explains findings, and opens a fix pull request after someone allowed confirms it. It also posts review alerts with buttons. If you only want alerts in a channel, an incoming webhook is the simpler option.

The same app is available for Microsoft Teams, Google Chat and Discord.

Install

1. In the console, open Integrations → Slack and choose Add to Slack. You need the settings.manage permission.
2. Pick the Slack workspace and allow access. You are linked to your Slack user automatically.
3. Map channels to repositories (see Channels, repositories and roles). By default the app does not answer in a conversation that no mapping covers.
4. Invite @MergeHarbor to the channels you mapped.

A Slack workspace belongs to one MergeHarbor organization at a time. Install once per workspace; installing across a whole Enterprise Grid organization is not supported.

What you can ask

Mention @MergeHarbor in a channel, or send it a direct message. In channels it answers in a thread under your message.

You write	MergeHarbor answers with	Credits
A pull request link, or summarise	The stored review summary, confidence, counts and up to ten findings	None
explain finding 2	One finding with its suggested change	None
status	Pull request state, review status, open findings and the latest fix PR	None
open a fix	A confirmation with the number of changes it would apply	None
help	What the app can do	None
Any other question, for example does this change the retry limit?	An answer from the same engine as Ask in the console	Yes

A question needs a pull request. Name it with a link (GitHub, GitLab, Bitbucket, Azure DevOps or a MergeHarbor console link) or as PR #12 in acme/payments, acme/payments#12 or MR !12 in group/app. Later messages in the same thread can leave it out: the app remembers which pull request the thread is about, so explain finding 2 works without a link.

Findings are numbered most severe first, in the order summarise lists them. Every answer ends with a View in MergeHarbor button and a line saying whether credits were used.

Questions and answers also appear in the console on the pull request, in the conversation called Questions from Slack. When you ask in a thread, a short redacted summary of up to 15 earlier messages in that thread is sent with the question for context.

Slash command

Command	Reply (only you see it)
/mergeharbor help	The command list
/mergeharbor link	A one-time link that connects your Slack user to your MergeHarbor account (valid for 15 minutes)
/mergeharbor status	The workspace, whether you are linked, and this channel’s role, repositories and credits used against caps

Fix pull requests

open a fix (or Open fix PR on an alert) needs:

• a linked Slack user,
• a channel whose role is fix or approver,
• an open pull request in that channel’s repositories, with at least one open finding that has a suggested change.

MergeHarbor posts a confirmation. The fix pull request, against the pull request’s branch, is opened only when someone allowed presses Open fix pull request:

• in a fix channel, the pull request’s author or an approver;
• in an approver channel, an approver only, even for the author.

Approvers are the people listed in the workspace settings or, when the list is empty, members whose role has the pulls.fix permission. Every confirmation is recorded in the audit log.

People

A Slack user is linked to a MergeHarbor member automatically when Slack reports a confirmed email address that matches an active member. Anyone else can link themselves with /mergeharbor link. People who are not linked get read-only answers: they cannot request or confirm fixes or mute alerts.

The console lists Slack users who asked without a link, so you can invite or link them.

Channels, repositories and roles

A mapping gives a channel a set of repositories and a role. Repositories can be every repository, a list, or the repositories your teams have access to.

Role	Allows
ask	Read-only answers
fix	Answers, and fix pull requests confirmed by the author or an approver
approver	Answers, and fix pull requests confirmed by an approver only

A mapping can target one channel, all public channels, all private channels (including group DMs), or direct messages. The most specific mapping wins: a mapping for the channel itself, then the one for that kind of conversation, then the workspace default for unmapped channels. The default is to answer nothing; you can change it to ask on every repository.

Private repositories stay out of public channels. A public channel sees a private repository only when that channel is mapped to it by name, never through “all public channels” or the default. MergeHarbor asks the code host whether a repository is public; when it cannot tell, it treats the repository as private.

/mergeharbor status and the console’s simulator show what applies to a person in a channel without running anything.

Credit caps

Each mapping can cap credits per calendar month (UTC): one cap for the whole channel and one per person in it. When a cap is reached, questions are refused until the next month; summaries, explanations and status keep working because they use no credits. Your organization’s credit budget applies as it does in the console.

Workspace settings

Setting	Default	What it does
Answer direct messages	On	Whether the app answers DMs
Code snippets in public channels	Off	When off, code blocks in answers are replaced by a note in public channels
Approvers	Empty	Who confirms fix pull requests; empty means members with pulls.fix
Unmapped channels	No answers	No answers, or ask on every repository

Alerts with buttons

Review alerts can go through the app instead of a webhook. In the destination, choose where they go:

• a channel you pick,
• every channel mapped to the pull request’s repository, or
• a direct message to the pull request’s author (when their Slack user is linked).

Findings alerts sent this way carry three buttons:

• Explain: the stored summary and findings, in the alert’s thread. No credits.
• Open fix PR: the same rules as open a fix.
• Mute repo 24h: stops alerts for that repository in that channel for 24 hours. Linked people only.

Activity log

Integrations → Slack lists every request: who asked, in which channel, what kind of request, the outcome, credits and cost, and a link to the thread. It does not store message text. Filter by channel, person, kind, outcome or date, and export up to 5,000 rows as CSV.

Permissions the app asks for

Slack scope	Why
app_mentions:read, im:history	See mentions and direct messages sent to the app
channels:history, groups:history	Read earlier messages of a thread when you ask in it
chat:write	Post and update answers
channels:read, groups:read	List channels for mappings
users:read, users:read.email	Link Slack users to members by confirmed email
commands	/mergeharbor

In the console, viewing the Slack pages needs settings.read; installing, changing settings and mappings, and removing links need settings.manage.

Data handling

• Verified requests. Every request from Slack is checked against Slack’s signature and must be less than five minutes old. Retries from Slack are ignored.
• Redaction. Message text is redacted of secrets before it is queued, and the queued copy is deleted once it has been handled. Everything the app posts is redacted too, and can never mention @channel, @here or a person, except the person who confirmed a fix or muted a repository.
• What is stored. Per thread, only which pull request it is about and a redacted summary of at most 2,000 characters, kept for 90 days after the last answer. Questions and answers are kept on the pull request like console questions. The activity log keeps no message text and is kept for 400 days.
• Tokens. The bot token is encrypted at rest and never returned by the API.
• Uninstall. Removing the app from the console revokes its token at Slack and deletes it. Removing it in Slack has the same effect. Mappings and links are kept and apply again if you add the workspace back.

Self-hosted installations

Self-hosted installations register their own Slack app from a manifest and set SLACK_APP_CLIENT_ID, SLACK_APP_CLIENT_SECRET and SLACK_SIGNING_SECRET. The manifest and steps are in docs/integrations/SLACK.md and docs/OAUTH_APPS.md, “Slack app”.