# MergeMe - Full Documentation Rendered docs: https://mergeme.dev/docs Concise overview: https://mergeme.dev/llms.txt --- ## Overview MergeMe delivers GitHub pull request and GitLab merge request notifications to Slack for code review. Each PR/MR gets one updating Slack card - status changes update the existing message in place rather than creating a new one. Comments are posted as thread replies on that card. Supported providers: GitLab.com, GitLab self-hosted, GitHub.com. Each MergeMe workspace can connect **multiple git sources at once** (e.g. GitHub + GitLab.com + self-hosted). Slack is still one connection per workspace. Channel and user mappings are tagged by git source; routing pickers list GitHub repos and GitLab projects in grouped dropdowns. Dashboard **Sources** sidebar: GitHub, GitLab.com, Self-hosted GitLab, Slack (separate pages). Onboarding asks for your **main** git platform first; you can connect the others later from Sources. --- ## Provider Comparison | | GitLab.com | GitLab Self-Hosted | GitHub.com | |---|---|---|---| | Auth method | OAuth (automatic) | None required | GitHub App install | | Webhook setup | Automatic via GitLab API | Manual - paste URL into GitLab | Automatic via GitHub App | | Project listing | Dropdown (from OAuth token) | Manual (enter project ID) | Dropdown (from App install) | | Terminology | MR / !42 | MR / !42 | PR / #42 | | Webhook signing | Signing token (HMAC-SHA256) | Signing token (GitLab 19.0+) or secret token fallback | X-Hub-Signature-256 (HMAC-SHA256) | | Who registers webhooks | MergeMe (automatically) | You (once per project) | GitHub App (automatically) | | CI status on Slack cards | Pipeline events registered automatically; enable in Preferences | Enable Pipeline events on the webhook; then enable in Preferences | Checks + Commit statuses (read); then enable in Preferences | | Scheduled stale reminders | Yes - Routing > Reminders | Not supported | Yes - Routing > Reminders | Which to choose: - GitLab.com: repos are hosted on gitlab.com. Easiest setup via OAuth. - GitLab Self-Hosted: you run your own GitLab instance. MergeMe can't reach it directly so you paste the webhook URL manually. - GitHub.com: repos are on github.com. Install the GitHub App on your org, no per-repo webhook setup needed. --- ## Installation: GitLab.com Prerequisites: - A MergeMe account (sign in at mergeme.dev with Google) - Maintainer or Owner access on the GitLab projects you want to track - A Slack workspace where notifications should appear Setup steps: 1. Create a workspace and choose GitLab.com as your main platform On first sign-in you'll be guided through onboarding. Pick GitLab.com as your starting source (you can connect GitHub or self-hosted GitLab later from Sources). 2. Connect Slack Open Sources → Slack and click Connect Slack. Authorise the MergeMe bot in your Slack workspace. 3. Connect GitLab.com Open Sources → GitLab.com and click Connect GitLab. You'll be redirected to gitlab.com to authorise MergeMe. MergeMe requests the `api` scope - required to register and manage webhooks on your projects. 4. Add channel mappings Open Routing → Channel mappings. Select a GitLab project from the dropdown (populated from your OAuth token), pick a Slack channel, and save. MergeMe immediately registers a webhook on that GitLab project. Repeat for each project you want to track. 5. Map users (optional) Open User Mappings. For each GitLab username, select the corresponding Slack user. When someone is @-mentioned in a GitLab comment, MergeMe will @-mention them in Slack. What MergeMe handles automatically: - Webhook registration on each GitLab project you map, including pipeline events for CI status on cards - Token refresh (OAuth tokens refreshed transparently before expiry) - Webhook cleanup when you remove a channel mapping --- ## Installation: GitLab Self-Hosted Prerequisites: - A MergeMe account (sign in at mergeme.dev with Google) - Maintainer or Owner access on the GitLab projects you want to track - A Slack workspace where notifications should appear - Your GitLab instance must be able to send outbound HTTP requests to api.mergeme.dev (cannot be fully air-gapped - GitLab initiates outbound HTTPS to deliver webhooks) Setup steps: 1. Create a workspace and choose Self-Hosted GitLab as your main platform On first sign-in, pick Self-Hosted GitLab as your starting source (other git sources can be added later). 2. Connect Slack Open Sources → Slack and click Connect Slack. 3. Copy your webhook credentials Open Sources → Self-hosted GitLab. You'll find: - Your Webhook URL (unique to your workspace) - A Signing token (recommended, GitLab 19.0+) - A Secret token (fallback for older GitLab versions) 4. Register the webhook in GitLab In your GitLab instance: Settings → Webhooks → Add new webhook. - Paste your Webhook URL - Paste the Signing token into the "Signing token" field (GitLab 19.0+) OR paste the Secret token into the "Secret token" field (GitLab < 19.0) - Enable: Merge request events and Note events. Also enable Pipeline events if you want CI status on Slack cards - Click Add webhook Repeat this for each project you want to track. Pro tip: On GitLab Premium or Ultimate, you can add the webhook once at the group level (group → Settings → Webhooks) instead of per project. Use the same MergeMe URL and tokens. Map only the project IDs you care about in the MergeMe dashboard. See GitLab group webhooks docs. 5. Add channel mappings Open Channel Mappings. Enter the project ID manually (found in GitLab under Settings → General), select a Slack channel, and save. 6. Map users (optional) Open User Mappings and map GitLab usernames to Slack users. Signing token vs secret token: - Signing token (GitLab 19.0+): HMAC-SHA256 signature over the request body with a timestamp. Provides body integrity and replay protection (5-minute window). - Secret token (all versions): plain value sent in a header. No integrity check or replay protection. Use the signing token if your instance is on 19.0 or later. Network requirements: - Self-hosted GitLab cannot be fully air-gapped. GitLab must reach api.mergeme.dev:443 outbound. - MergeMe does not connect inbound to your GitLab instance. Troubleshooting: - Webhook test fails: check that your GitLab instance can reach api.mergeme.dev on port 443. - No Slack message after merging: confirm Merge request events is enabled on the webhook. - Comments not appearing: confirm Note events is enabled on the webhook. - CI line never appears: enable Show CI status on Slack cards under Routing > Preferences, and confirm Pipeline events is enabled on the webhook. - Wrong project: verify the project ID in Channel Mappings matches the GitLab project ID. --- ## Installation: GitHub.com Prerequisites: - A MergeMe account (sign in at mergeme.dev with Google) - Owner access on the GitHub org or account you want to connect - A Slack workspace where notifications should appear Setup steps: 1. Create a workspace and choose GitHub.com as your main platform On first sign-in, pick GitHub.com as your starting source (you can add GitLab sources later from Sources). 2. Connect Slack Open Sources → Slack and click Connect Slack. 3. Install the GitHub App Open Sources → GitHub and click Install GitHub App. You'll be redirected to GitHub. Select your org or account, choose which repos to grant access to, and click Install. You'll be redirected back to MergeMe automatically. 4. Add channel mappings Open Channel Mappings. Select a repository from the dropdown (populated from the App installation), pick a Slack channel, and save. No webhook registration needed - the GitHub App handles it. 5. Map users (optional) Open User Mappings and map GitHub usernames to Slack users. Permissions the GitHub App requests: - Metadata: Read - mandatory for all GitHub Apps, enables repo listing - Pull requests: Read - read PR data and receive PR webhook events - Issues: Read - required for PR comment events (GitHub sends general PR body comments as issue_comment events) - Checks: Read - CI status on Slack cards (GitHub Actions check runs) - Commit statuses: Read - CI status on Slack cards (legacy commit statuses such as Jenkins) MergeMe does not request any write permissions. If you decline the Checks/Commit statuses prompt, cards keep working without the CI line. Events subscribed to: - pull_request (opened, closed, merged, review requested) - pull_request_review (approved / changes requested / dismissed) - pull_request_review_comment (inline diff comments) - issue_comment (general PR body comments, filtered to PRs only) - check_run, check_suite, and status: CI updates for the optional Slack card line --- ## Webhook Reference ### Webhook URLs GitLab.com: https://api.mergeme.dev/webhooks/gitlab/{workspaceId} GitLab Self-Hosted: https://api.mergeme.dev/webhooks/gitlab/{workspaceId} GitHub.com: https://api.mergeme.dev/webhooks/github The {workspaceId} for GitLab URLs is your workspace's unique identifier, shown on Sources → Self-hosted GitLab. GitHub uses a single shared URL; workspace identity is determined from the installation_id in the webhook payload. ### Webhook Authentication GitLab signing token: header `webhook-signature`, format: `v1,` GitLab secret token: header `X-Gitlab-Token`, format: plain secret value GitHub: header `X-Hub-Signature-256`, format: `sha256=` GitLab signing tokens also include `webhook-id` and `webhook-timestamp` headers. Requests with a timestamp older than 5 minutes are rejected (replay protection). ### Supported Events GitLab: - merge_request: MR opened, closed, merged, review requested - note: comment on MR body or thread - pipeline: pipeline status changes (when CI status on cards is enabled) GitHub: - pull_request: PR opened, closed, merged, review requested - pull_request_review: review submitted (approved / changes requested / dismissed) - pull_request_review_comment: inline diff comment - issue_comment: general PR comment (filtered to PRs only) - check_run / check_suite / status: CI check updates (when CI status on cards is enabled) ### Slack Message Trigger States MergeMe posts or updates the Slack message when a PR/MR transitions to: - open: PR/MR opened or reopened - in_review: reviewer requested, or a review was dismissed - approved: all required reviewers approved - changes_requested: a reviewer requested changes - merged: PR/MR merged - closed: PR/MR closed without merging Comments post as thread replies on the existing Slack message. When CI status on cards is enabled (Routing > Preferences), the card also shows a rollup CI line (e.g. CI: Running (2/5)) that updates in place as GitHub checks or GitLab pipelines run. Optional (non-blocking) checks appear as a second bucket (e.g. Optional CI: Passed (1/1)). --- ## Reminders Scheduled Slack digests of stale open PRs/MRs. Configure under Routing > Reminders. - Independent of channel mappings - a repo can be on a reminder without a mapping - GitHub.com, GitLab.com, and self-hosted GitLab in Application mode (manual webhooks cannot be scanned) - Each reminder: one or more repos, one Slack channel, IANA timezone, weekdays, time on a 15-minute grid - Age is measured from created_at; optional max age, skip drafts, excluded usernames, post-when-empty - One run per local calendar day; missed 15-minute windows are not caught up the same day - Slack lists the 10 newest matches by created date, then "+N more" - Hobby: 1 reminder with 1 repo. Team: unlimited reminders, up to 25 repos each - Scan failures are stored on the reminder row and are not posted to Slack --- ## Routing preferences Workspace-wide settings under Routing > Preferences: - **Excluded usernames** - blocklist bots and automation accounts (up to 50) - **When to post the Slack card** - on open, when ready for review (default), or after a phrase comment - **Show PR/MR number in card title** - on by default - **Show CI status on Slack cards** - off by default; adds a CI rollup line to each card for GitHub checks and GitLab pipelines. GitHub needs Checks: Read and Commit statuses: Read. GitLab.com mappings register pipeline events automatically; self-hosted GitLab must enable Pipeline events on the webhook. --- ## FAQ ### Which provider should I choose? Use GitLab.com if your repos are on gitlab.com. Use GitHub.com if your repos are on github.com. Use GitLab Self-Hosted if you run your own GitLab instance. ### Can I connect more than one git provider in one workspace? Yes. One workspace can use GitHub.com, GitLab.com, and/or self-hosted GitLab at the same time. Connect each from Sources. Channel mappings and user mappings are scoped per git source. ### Can I have multiple MergeMe workspaces? Yes - for example separate teams, or one MergeMe workspace per Slack workspace you use. ### Can I connect more than one Slack workspace? Each MergeMe workspace connects to one Slack workspace. Create separate MergeMe workspaces for different Slack workspaces. ### My webhook isn't firing (self-hosted GitLab) - how do I debug it? In GitLab: Settings → Webhooks → find your webhook → click Test. GitLab shows the response code. A 200 means it's working. Common issues: - Your GitLab instance can't reach api.mergeme.dev - check firewall / outbound rules - The signing or secret token doesn't match what's in MergeMe's Installation tab - Wrong event types enabled - make sure Merge request events is checked (and Pipeline events for CI status) ### What's the difference between the signing token and the secret token? The signing token (GitLab 19.0+) creates an HMAC-SHA256 signature over the request body with a timestamp, providing body integrity and replay protection. The secret token sends a plain value in a header with no integrity check. Use the signing token if your instance is on 19.0 or later. ### Do I need to add a webhook for every project (self-hosted)? By default, one webhook per project, all pointing to the same MergeMe URL. On GitLab Premium or Ultimate, you can use a single group webhook on the parent group instead and map project IDs in MergeMe. GitLab.com and GitHub.com manage webhooks automatically. ### Can I use MergeMe with an air-gapped GitLab instance? No. GitLab must make outbound HTTPS requests to api.mergeme.dev to deliver webhook events. MergeMe does not connect into your network. ### What OAuth scopes does MergeMe request from GitLab.com? The `api` scope. This is the minimum scope that allows webhook management (creating and deleting project webhooks). No narrower scope covers this operation. ### What happens if I revoke MergeMe's GitLab OAuth access? Existing webhooks remain on your GitLab projects. MergeMe can no longer refresh its token but will still process incoming webhooks. Reconnect via Sources → GitLab.com in your dashboard. ### What permissions does the GitHub App request? Metadata: Read (required), Pull requests: Read, Issues: Read, plus Checks: Read and Commit statuses: Read for optional CI status on Slack cards. No write permissions are requested. If you decline the Checks/Commit statuses prompt, cards keep working without the CI line. ### Can I limit which repos the GitHub App can access? Yes. During installation on GitHub, choose "Only select repositories". Change this later in your GitHub org/account settings under Installed GitHub Apps. ### What happens if I uninstall the GitHub App? GitHub notifies MergeMe, which clears the installation and removes your channel and user mappings. Notifications stop. Reconnect via Sources → GitHub and reconfigure routing. ### What happens if I remove MergeMe from Slack? Slack notifies MergeMe, which clears Slack access and removes your channel and user mappings. Reconnect via Sources → Slack and re-add mappings. ### How do user mappings work? When MergeMe receives a webhook event, it checks the author's username. If a mapping exists, MergeMe @-mentions the corresponding Slack user. Without a mapping, the username appears as plain text. ### What events cause a Slack message to be sent? PR/MR state transitions: opened, in review, approved, changes requested, merged, closed. One Slack message per PR/MR, updated in place. Comments post as thread replies. ### Does MergeMe show CI status on Slack cards? Yes, when enabled under Routing > Preferences. MergeMe adds a CI rollup line to each PR/MR card (for example CI: Running (2/5)) for GitHub checks and GitLab pipelines. Off by default; no separate thread messages for CI events. GitHub needs Checks: Read and Commit statuses: Read. Self-hosted GitLab must enable Pipeline events on the webhook. ### Does MergeMe send reminders for stale PRs/MRs? Yes. Under Routing > Reminders, schedule a Slack digest of open GitHub PRs and GitLab.com MRs older than a threshold you set. Reminders do not require channel mappings and do not support self-hosted GitLab. ### How do I stop notifications for a specific project? Remove the channel mapping for that project. For GitLab.com, the webhook is deleted automatically. For self-hosted GitLab, also remove the webhook in GitLab manually.