Install guide

From marketing site to first PR review, in three steps.

A GitHub App, a Slack channel, and a verify checklist. No SDK, no CI plumbing, no daemon to run — just the install flow below, in under five minutes.

Step 1 — GitHub App

Install the Mergehound GitHub App.

From GitHub Marketplace, pick scope (single repo vs whole org), confirm the permissions, and the App wires itself up. We never request write access to your source.

Recommended for first install
Single repo first

Install on one repo, prove the review read, then expand org-wide on your call. The narrowest blast radius.

  • Pick the repo where one PR a day changes — a service you actively ship.
  • Mergehound can review that repo alone; we never see the rest of your org.
  • Roll out to the next repo after the first PR review lands.
Whole org at once

Install on the org and grant access to every repo the App is authorized for. Best for greenfield teams with one repo per service.

  • Authorize every current repo in one install flow.
  • Per-repo review settings are still scoped from inside the dashboard.
  • Revoke the App from any repo in GitHub settings — no support ticket needed.
PermissionRequested scopeWhat it means in plain English
Pull requestsReadRead PR titles, descriptions, the diff, and review comments — everything we need to write a review.
IssuesRead & writeRead existing PR review comments; post inline annotations as mergehound-bot. We never open or close issues.
MetadataReadRead the repo name, default branch, and visibility — to label reviews and route them correctly.
ContentsNoneWe never push, commit, branch, rebase, or merge on your behalf. No source writes, ever.
WebhooksPR eventsSubscribe to opened/synchronize/reopened so we know when a review should kick off. No write webhooks.

Full permission reference and revocation steps are on the security page.

Step 2 — Slack

Connect the daily digest.

A morning Slack post that summarises open PRs awaiting review, regressions pinned to your baseline, and OWASP findings since yesterday. One channel. One post a day.

Slack workspace

Three steps, then the digest posts tomorrow.
~90 seconds
  1. Sign in with Slack

    From the dashboard, click "Connect Slack." Slack shows you the bot identity (mergehound) and the scopes it requests — message:write to one channel, users:read for display names, nothing else.

  2. Pick a channel

    We post the daily digest to one channel you choose — usually #eng-review or #frontend-prs. The bot adds itself to that one channel and nowhere else; we never DM users or read message history.

  3. Confirm the first delivery

    The next morning at 09:00 in your Slack timezone, the digest posts: open PRs awaiting review, regressions vs main, and OWASP findings since yesterday. Adjust the time and channel from the dashboard anytime.

09:00 digest

Posts once a day, in your Slack workspace timezone.

One channel

Posts to the channel you choose. No DMs, no message-history reads.

Opt out anytime

@mergehound unsubscribe or remove the app from your Slack admin.

Step 3 — Verify

Verify it's working.

Five checks that turn the marketing pitch into a working pipeline. Expect the first PR review within ~30 seconds of opening a draft.

Verify checklist

Five checks, in order.
  1. 01 Open a draft PR on the installed repo

    Make a small change — a typo fix is fine — and open a draft PR. Mergehound comments within ~30 seconds on most codebases.

  2. 02 Confirm mergehound-bot posted an inline comment

    Look for the mergehound-bot avatar next to the PR review. If it posted, the GitHub App pipeline is wired end-to-end.

  3. 03 Check the Slack digest channel

    You should see a card from the mergehound app showing your draft PR. If it landed, the Slack handshake is live.

  4. 04 Open the dashboard overview

    The /app overview should show the new repo, its review status, and recent findings. Audit log export is on Pro/Enterprise.

  5. 05 Promote to the rest of the org (when ready)

    Once the first review looks right, expand the install to more repos or to the whole org from GitHub settings — no reinstall needed.

What a review looks like

Sample PR
acme/checkout-servicePR #482 · feat: JWT hardening + rate-limit alert
mergehound · 3 findings
  • src/lib/auth/session.tsTS
  • src/lib/rate-limit.tsTS

@@ -42,7 +42,9 @@ export async function verifySession

  • 42
  • const token = req.headers.get('authorization')?.slice(7)
  • if (!token) throw new SessionError('missing token')
  • return jwt.verify(token, process.env.JWT_SECRET)
  • }
    Alert

    Pin the JWT algorithm to HS256.

    Without an explicit algorithms list, jwt.verify will accept any algorithm the token advertises — including "none" on misconfigured libs. Pin to an allow-list before merging.

  • const decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] })
  • if (Date.now() - decoded.iat * 1000 > MAX_TOKEN_AGE_MS) {
    Info

    Token age check looks right.

    Comparing decoded.iat against MAX_TOKEN_AGE_MS prevents replay of long-lived session tokens. Verified against the OWASP ASVS V3 session-timeout control.

  • throw new SessionError('token too old')
  • }
  • return decoded
  • }

@@ -110,4 +114,6 @@ export async function enforceRateLimit

  • 114
  • const count = await redis.incr(key)
  • if (count > limit) throw new RateLimitError()
  • if (count === limit + 1) {
  • await notifyOncall(key, count)
    Alert

    Pin the JWT algorithm to HS256.

    Without an explicit algorithms list, jwt.verify will accept any algorithm the token advertises — including "none" on misconfigured libs. Pin to an allow-list before merging.

  • }
  • return { count, remaining: Math.max(0, limit - count) }
    Info

    Token age check looks right.

    Comparing decoded.iat against MAX_TOKEN_AGE_MS prevents replay of long-lived session tokens. Verified against the OWASP ASVS V3 session-timeout control.

3 inline commentsmergehound-bot · posted ~30s after PR opened

Static preview — what you see in your inbox when Mergehound posts its first inline review comment. No real data, no real repo.

Or via URL

Hand it to a teammate.

No CLI required. The Marketplace install flow is the only path — and the URL below opens directly into the right place in the GitHub UI.

Shareable install URL
https://github.com/apps/mergehound/installations/new

Drop this in your team's onboarding doc or DM it to the engineer setting up reviews — it lands directly on the scope + permissions confirmation step.

Ready when you are

Past the install? Run your first review.

If you hit anything unexpected during the install — a missing permission, an org the App can't see, a Slack channel that won't accept bots — drop us a line and we'll route it to a human.