Routes
A notification route connects events to a channel: send these events about these projects to this Slack channel. With several routes, each team can get the events of its own projects, security can get every finding by email, and an outbound webhook can receive everything for your own systems.
Company page → Notifications → Notification routes, and the What is announced card above it. Company admins of the company and platform admins change them; they are saved with Save changes (see Saving). None of them is held for four-eyes review.
What is announced
Which events are sent to the notification routes below (each route picks its events). These switches apply to the whole company, before any route or person is looked at.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Watched repositories | Events of watched repositories are sent too (otherwise only projects under change management announce). Off: no event about a watched repository or a watched merge request reaches any route or person, webhooks included | Off | On, off | Company admin, platform admin | monitoring.notify |
| Direct changes | A change reached a watched branch without a merge request (watched repositories follow the setting above). Off: Direct change to a watched branch and Branch protection weakened are not sent | On | On, off | Company admin, platform admin | direct_changes.notify |
| New vulnerabilities on default branches | Announced as the vulnerability_found event: one message for each round of checks, naming the projects and the worst findings first, linked to the vulnerability inventory. The lowest severity announced | High and above | Critical only, High and above, Medium and above, Low and above, Every severity, unrated too, Never | Company admin, platform admin | vulnerabilities.notify_min_severity: critical, high, medium, low, unknown, none |
These settings are also described where they belong: Watching repositories, Direct changes → Notifications and Scanning → Vulnerability tracking.
Notification routes
Route notifications to Slack, Teams, email or your own endpoint by project path. Every active route whose events and path patterns match gets the event, in the order below; a route marked "Stop here" keeps it from the routes after it. A route with path patterns gets only events of a project they match. Failed sends are retried; each route shows its recent deliveries. See How an event is routed.
Without routes the card says No notification routes yet (Add a route to send notifications to Slack, Teams or email.). Add route adds one at the end of the list, opened.
The route list
Each route is one row, numbered in order (#1, #2 …). Clicking the row opens or closes it. The row shows:
- the route's name (Unnamed route when it has none);
- its channel (Slack, Teams, Email or Webhook);
- Active or Inactive;
- Stop here when the route stops the routes after it;
- a red N failed badge when deliveries to it failed for good in the last 7 days (see Delivery log and failures);
- how many path patterns it has (N patterns);
- Every event, or how many events it takes (N events);
- a dot: green Channel configured or amber Channel not configured (see Channels).
The arrows Move route up and Move route down change the order. The bin, Remove route, removes the route. Both take effect with Save changes.
Route settings
| Setting (label in the UI) | What it does | Default for a new route | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Route name | Names the route in the list, in the delivery log and in the footer of its messages (Route name (e.g. Backend Team)) | Empty | Any text; may be empty | Company admin, platform admin | name |
| Channel | Where the route sends: see Channels | Slack | Slack, Teams, Email, Webhook | Company admin, platform admin | channel_type: slack, teams, email, webhook |
| Active | An inactive route is kept but receives nothing (Send test still works) | On | On, off | Company admin, platform admin | active |
| Webhook URL, Recipients, Signing secret | The channel's own fields: see Channels and Outbound webhooks. An email route whose recipients include addresses of deactivated people shows These addresses belong to deactivated people, who still get this route's emails: … | Empty | Company admin, platform admin | webhook_url, recipients, secret | |
| Path patterns | Glob patterns matched against project path (e.g. group/*, group/api). Leave empty to match all projects. Type a pattern and press Enter (group/project/* then Enter). See Path patterns | Empty: every project | Patterns, one at a time | Company admin, platform admin | path_patterns (list of strings) |
| Events | The events the route takes, one checkbox each, and Every event. Ticking Every event clears the others; ticking an event clears Every event. See Events | Every event | Every event, or any of the events; at least one | Company admin, platform admin | events: ["all"] or a list of event values |
| Stop here | An event this route takes goes to no route below it. A route that cannot send (an email route without a mail server) does not stop anything. See How an event is routed | Off | On, off | Company admin, platform admin | stop |
A saved route also has Send test and Recent deliveries (see Send test and Recent deliveries).
Path patterns
A route with path patterns takes only events about projects whose full path (such as payments/api or acme/backend/billing) matches one of them. Matching is case-sensitive and covers the whole path.
| Pattern | Matches |
|---|---|
group/* or group/** | group itself and every project under it, at any depth: group/api, group/sub/api |
group/api | That project only |
group/api-* | * stands for any characters within one part of the path: group/api-v1, group/api-v2, but not group/x/api-v1 |
group/ap? | ? stands for one character: group/api, group/apx |
group/[ab]pi | A character from the brackets: group/api, group/bpi |
/* at the end matches deeper projects too; this differs from policy patterns, where * stays within one level.
An event that is not about a project (such as a connection problem, or a background job that failed outside any repository), or about a repository that is not registered in Merge Pilot, has no project path: a route with path patterns does not take it, whatever its channel.
How an event is routed
- Is it held back? Events about imported merge requests, merge requests left watched, and watched repositories while Watched repositories is off are dropped, and some events have company switches of their own (see What holds events back).
- Is it new? An event about the same thing in the same state as one already sent is not sent again (see Sent once per on Events).
- Every matching route, in order. The routes are looked at from the top. A route matches when it is active, its events include the event (or Every event), and it has no path patterns or one of them matches the event's project path. Every matching route gets the event, whatever its channel.
- Stop here. After a matching route with Stop here, the routes below it are not looked at.
- Routes that cannot send are skipped. An email route while the company has no mail server is passed over, and its Stop here with it: the routes below still get the event.
- People. Besides the routes, the event is emailed to the people it concerns (see Personal notifications). A person whose address one of the event's email routes already has gets that route's email only.
So one event becomes one delivery for each matching route up to the first that stops, plus one email per person. Notification not delivered never goes to the route it is about, and that route's Stop here does not count for it (see Delivery log and failures). New vulnerability on a default branch is matched project by project: each route gets one message with the projects it takes (see Events).
Ordering routes
Put routes that should keep their events to themselves first, with Stop here, and broad routes last. For example:
| # | Route | Path patterns | Events | Stop here |
|---|---|---|---|---|
| 1 | Payments team (Slack) | payments/** | Every event | On |
| 2 | Security (Teams) | Secrets found in a merge request, Vulnerable dependency introduced by a merge request | Off | |
| 3 | Audit archive (Webhook) | Every event | Off |
- Secrets found in
payments/apigo to route 1 only: it matches and stops. - Secrets found in
web/shopgo to routes 2 and 3. - A connection problem goes to route 3: it has no project path, so route 1 does not take it, and route 2 does not take that event.
Without Stop here on route 1, secrets in payments/api would reach all three routes.
Repeats and timing
Each event is sent when it happens; there are no quiet hours. What Merge Pilot notices again (a re-scan, another evaluation of the same commit, a push found both by its webhook and by the head check) is not sent again: each event is sent once per what its Sent once per column on Events names, for 30 days, or within the time given there. Events that would repeat for every person or job are limited further: Background job failed once an hour per connection and kind of failure, Identity provider unreachable once an hour per provider, Approval fatigue once per approver within the company's lookback days, New vulnerability on a default branch one digest per round of checks.
When sending fails
Every route's messages are queued, then sent and tried up to 5 times in all, with a growing wait between attempts (30 seconds, then doubling up to 5 minutes). A mail server's permanent refusal is not retried. A delivery that fails for good is written to the audit log, counted on the tab and announced to the other routes as Notification not delivered. All of it, and the meaning of each status, is on Delivery log and failures.
Recent deliveries
A saved route of any channel shows Recent deliveries below its settings: its latest 50 deliveries, newest first, each with its status, event, time, attempts and last answer or error, and Send again. The company's Delivery log shows every route's and person's deliveries with filters. See Delivery log and failures.
API
Routes are part of the company: GET /api/v1/companies/{id} returns notifications.routes, and PUT /api/v1/companies/{id} with notifications replaces the whole list, in the order given (see Company API). The What is announced settings are the monitoring.notify, direct_changes.notify and vulnerabilities.notify_min_severity fields.
Each route:
| Field | Meaning |
|---|---|
id | The route's ID. Send it back unchanged: the saved webhook URL and signing secret are kept by it. A route sent without one gets a new ID. Two routes cannot have the same ID |
name | Route name |
channel_type | slack, teams, email or webhook |
webhook_url | Write-only. Empty or left out: the saved URL is kept |
has_webhook_url | In answers: whether a URL is saved |
secret | Webhook routes only, write-only. Empty or left out: the saved secret is kept |
has_secret | In answers: whether a signing secret is saved |
recipients | Email routes: the addresses |
path_patterns | The path patterns; empty for every project |
events | ["all"], or event values from Events |
active | true or false |
stop | true: an event this route takes goes to no route after it |
A save is refused with 400 when two routes have the same id: route id "<id>" is used by more than one route. Each route keeps its own ID, so copy a route by sending it without an id.
A save is also refused with 400 and a message naming the route (its name, or #<position> without one) when a route:
- has another
channel_type: channel_type must be slack, teams, email or webhook; - has no events, or an unknown one: choose at least one event, "<value>" is not an event (use all or one of …);
- is a Slack or Teams route without a URL (sent now or saved before), or with one that does not start with
http://orhttps://: needs a webhook URL, needs an http(s) URL; - is a webhook route without such a URL or without a signing secret: invalid input: webhook route "<name>" needs an http(s) URL and a secret;
- is an email route while the company has no mail server (after the save): set up the mail server (SMTP) before adding an email route;
- is an email route without recipients, or with one that is not a plain address: add at least one recipient, "<value>" is not an email address.
Creating a company (POST /api/v1/companies) with notifications checks the routes the same way; a new company has no mail server, so it cannot have email routes yet.
The deliveries, route tests and failure counts have their own endpoints: see Delivery log and failures → API.
Related pages
- Channels: each channel's fields and the mail server.
- Events: every event and what holds it back.
- Personal notifications: emails to the people an event concerns.
- Delivery log and failures: retries, the delivery log, Send test.
- Outbound webhooks: payload and signature.
- Notifications: the overview.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →