Learn these once and every screen in the control panel reads the same way. Each section explains how GitHub, GitLab, Slack and Discord differ where it matters.

Connections

A connection is a GitHub, GitLab, Slack or Discord workspace authorised once and shared by every route. Signing in with Google, GitHub, GitLab or Discord is only for your ForgeRelay account — it is not a forge or chat connection.

Topic	GitHub	GitLab	Slack	Discord
How you connect	GitHub App install	OAuth, then Watch projects	OAuth workspace	Bot install into a server
Webhook proof	HMAC signature	Per-connection token	—	—
Discovery	Repos from the App install	Watch + refresh	Channel list	Guild channel sync

GitHub: the App install is claimed from the control panel; installation webhooks only update an already-linked install
GitLab: after OAuth, Watch each project so ForgeRelay can create or update its project webhook
Slack can join channels and accepts slash commands; Discord is outbound delivery only
Pausing a repository ignores inbound webhooks for that repo — no chat messages until you turn it back on

Routes

A route sends one repository (or all repositories) into one Slack or Discord channel. When you create a route you pick a rule type: Pull request (reviews stay in threads) or Commits (one filtered digest per push). GitHub wording is pull request and checks; GitLab wording is merge request and pipeline.

For pull request routes, when several could match ForgeRelay picks the most specific: exact repository, then base-branch match, then label-include match, then an account-wide route.

Pull request presets: Review essentials (PR lifecycle), Full lifecycle (PR + CI), Pipeline monitoring, or Custom
Commits presets include Default branch CI for post-merge default-branch pipeline alerts
Optional PR filters: base branches, include or exclude labels, include drafts, suppress bot authors
One living root message per request and channel; later activity updates that card and may reply in the thread
Slack threads use the parent message timestamp; Discord opens a thread on the first post and replies into it

Events

Events are the activity a route relays. They group into lifecycle, conversation and CI. Approved and changes requested both come from a submitted review — ForgeRelay branches on the review state rather than expecting separate forge event names.

Lifecycle

Opened or reopened, ready for review, reviewer requested, approved, changes requested, merged or closed.

Conversation

Discussion and review comments, including GitHub line comments and GitLab diff notes as thread lines.

Started, passed, failed, canceled and recovered — classified from check or pipeline changes, then filtered by pipeline notify settings.

Concern	GitHub	GitLab
Lifecycle activity	Pull request events plus reviews and comments	Merge request events plus notes
Reviews	Review requested and submitted, with review body when present	Approvals map to a submitted review; reviewers come from the MR
CI shape	Check runs for each job, plus check suites and workflow runs to refresh cards	Pipeline snapshots plus Job Hooks so every parallel job stays visible

The route editor exposes only supported lifecycle and delivery controls. Older saved routes may show a warning when they contain retired controls. Push and tag activity is covered under Commit digests — a separate route type, not another pull request event.

Commit digests

Reviews stay in threads. Direct-to-main stays visible. A Commits route posts one filtered digest when commits land by push — complementary to pull request routes, not a Features switch. Push webhooks may arrive from GitHub or GitLab whenever the forge is subscribed; ForgeRelay ignores them unless a matching Commits route is enabled.

Events: branch push with commits, force push, tag created, tag deleted
Presets: Main only, Conventional feat/fix, Release tags, or Custom
Filters: watched branches, suppress bots, skip merge commits, optional path filters, skip pushes that only update an open pull request head
Digest display: brief list, titles only, or tip commit; list cap (5 / 10 / 20); fixed or force-push warning accent
Delivery timing is per route: immediate (default) or daily rollup — daily needs the workspace Daily digest feature turned on; immediate routes still post on each push
GitHub needs Contents: read and the Push webhook subscription; GitLab project hooks include push (and tag push) events — unmatched pushes stay ignored

Workspace defaults

Organisation Features set the baseline for every route: lifecycle cards, threaded comments, threaded reviews, reviewer mentions and review reminders. On a pull request route, each behaviour is Default, On or Off — Default inherits the workspace switch; On or Off forces that route.

Route features you will recognise: one thread per request, mention mapped reviewers, diff summary, link to GitHub or GitLab, compact messages, relay discussion comments, stale review reminder, pipeline status
Reminder delay is a workspace policy (about four hours by default), not a per-route timer
Daily digest unlocks per-route daily rollup timing on Commits routes — it does not turn commit digests on by itself
Plans meter unique mapped people under People, not how many teammates log into ForgeRelay

Identity mapping

A mapping pairs a GitHub or GitLab username with a Slack or Discord user for one chat workspace. The same person may map into Slack and Discord separately; they cannot map twice into the same destination connection.

Mapped people appear as native Slack or Discord mentions whenever their forge username shows on a card; unmapped names stay as handles
Mappings apply whenever a username is shown — not only when “mention mapped reviewers” is On
Create mappings on People; Slack can suggest matches from email, Discord uses search (two or more characters) instead of dumping the whole server roster
GitHub Apps usually cannot supply collaborator emails, so GitHub-sourced people often need a manual pick
Free and Team plans cap how many unique forge people you can map

Reminders

When a reviewer is requested and reminders are enabled, ForgeRelay schedules one quiet nudge in the existing pull or merge request thread if that review is still waiting after the workspace delay.

Default delay is about four hours; product behaviour is one reminder, not a repeating loop
The reminder cancels when the reviewer submits a review or is no longer pending
The elapsed delay is workspace-wide and can be set from 1 to 168 hours
Gated by the workspace review reminders feature and the route’s stale review reminder Default / On / Off

Pipeline status

GitHub checks and workflows and GitLab pipelines share one policy. ForgeRelay classifies each change as failed, recovered, passed, pending or canceled, then decides whether to notify.

Notify on: Failures only, Failures and recovery (default), or All changes
Pull request Pipeline monitoring is PR and MR checks only — it does not watch the default branch after merge
On a Commits route, Default branch only posts a channel message when that branch’s pipeline fails or recovers, even if Skip merge commits prevented a digest
Use “pipeline” wording for GitLab routes and “checks” for GitHub; the controls are the same

Deliveries and replay

Activity keeps two layers: inbound webhook deliveries from GitHub or GitLab, and outbound delivery attempts to Slack or Discord. Failed attempts retry automatically (up to five tries with backoff). You can also replay from the log.

Replay a webhook to re-run routing and message creation from the stored payload
Replay a delivery attempt to send the same outbound message again once the destination is healthy
Ignored deliveries (paused repository, unsupported event) are expected — not the same as a failure
GitHub and GitLab dedupe by delivery id so a forge retry does not double-post; a manual replay is intentional reprocessing

Reference

Event glossary and a delivery payload.

Glossary keys match the route editor. The sample payload is conceptual — ForgeRelay is not a public webhook-forwarding API; delivery records keep enough context to make a replay match the original.

opened Pull or merge request opened or reopened
ready Draft marked ready for review
reviewer_requested A reviewer was requested; mentions the mapped Slack or Discord user when linked
approved An approval was recorded (from a submitted review)
changes_requested A reviewer asked for changes (from a submitted review)
merged The request was merged or closed; the thread summary updates
comments A discussion or review comment, including line notes when present
pipeline_failed Checks or pipeline transitioned to failure
pipeline_recovered Previously failing checks or pipeline are green again
pipeline_passed Checks or pipeline completed successfully (when notify-on includes all changes)
pipeline_started Checks or pipeline became pending or started (when notify-on includes all changes)
pipeline_canceled Checks or pipeline canceled or skipped (when notify-on includes all changes)
push_commits Branch push with one or more commits; posts a filtered digest when a Commits route matches
push_forced Force push to a watched branch
tag_created A tag was created
tag_deleted A tag was deleted

{
  "event": "pipeline_failed",
  "route": "rt_04",
  "source": { "provider": "gitlab", "repo": "platform/edge", "mr": 77 },
  "destination": { "provider": "discord", "channel": "#deploys" },
  "pipeline": {
    "transition": "failed",
    "branch": "main",
    "sha": "7c1ab90",
    "duration_seconds": 252,
    "failed_jobs": ["integration-tests", "lint"]
  },
  "delivery": { "id": "evt_8836", "status": "ok", "thread": "existing" }
}

Concept content early access

Examples on this page use the same sample workspace as the control panel: northwind/api and platform/edge relaying into #eng-reviews and #deploys through routes rt_01 to rt_04.

Ready to route something real?

The control panel walks through connections, routes and identity mapping in order.

Open control panel See integrations