Notifications
Merge Pilot tells people when something needs their attention or should be on record: a change approval waiting for a decision or past its deadline, a blocked merge request, a merge without approval, secrets or vulnerable dependencies in a merge request, a direct push to a protected branch, a connection that stopped working. Each company decides which events go to which team channels, and each person decides which of the emails addressed to them they get.
Channels
A notification goes to a route's channel, or to a person:
| Channel (label in the UI) | Where it goes | Set up with |
|---|---|---|
| Slack | A Slack channel, as a message with a coloured bar | The channel's Slack incoming webhook URL |
| Teams | A Microsoft Teams channel, as an Adaptive Card | The channel's Teams Workflows webhook URL |
| A list of email addresses, one message each | The company's mail server (SMTP configuration) and the recipients | |
| Webhook | Your own HTTP endpoint, as signed JSON | An http(s):// URL and a signing secret |
| Personal email | The people an event concerns: a change approval's assignee, a merge request's author, the company admins | The company's mail server; each person's choices in My profile → Notifications |
Every message links to its page in Merge Pilot and says why it was sent. Every delivery is queued, retried when sending fails and kept for 7 days in the Delivery log (see Delivery log and failures). Each channel is described field by field in Channels, the outbound webhook in Outbound webhooks, personal emails in Personal notifications.
How it fits together
Notifications are set up per company. There are no platform-wide notification settings: each company has its own routes and its own mail server.
- Events are what happened, such as Merge request blocked or Connection problem. Every event, when it is sent and how often: Events. The same event about the same thing is sent once, however often Merge Pilot notices it.
- Routes connect events to a channel. A route names a channel, the events it takes and, optionally, the projects it covers (path patterns). Every active route that matches gets the event, in the routes' order; a route marked Stop here keeps it from the routes after it. See Routes.
- People get the events addressed to them by email, besides the routes, unless they turned them off. See Personal notifications.
- What is announced decides, for the whole company, whether watched repositories and direct changes send notifications at all, and from which severity new vulnerabilities on default branches are announced. See What is announced.
A company with no active route sends nothing to channels; personal emails still go out when it has a mail server. Turning on a route is one of the steps of the company's setup checklist (Turn on a notification channel, see Set up this company).
Where to set it up
Administration → Company (platform admins: Administration → Companies → the company), tab Notifications. The tab has:
- a red banner when deliveries failed in the last 7 days, with Show failed deliveries;
- What is announced: the company-wide switches;
- Notification routes: the routes, in order, each with Send test and Recent deliveries;
- SMTP configuration: the mail server for email routes and personal emails, with Send test email;
- Delivery log: every delivery of the last 7 days, filtered by status, route and event.
Everything on the tab is saved with Save changes at the bottom of the company page, together with the other tabs (see Saving). Four-eyes review does not hold notification settings: they apply as soon as they are saved.
Personal choices are in My profile → Notifications, for each person (see Personal notifications).
Who may do what
| Role | Notifications |
|---|---|
| Platform admin | Sets up the notifications of any company; sees its deliveries |
| Company admin | Sets up the notifications of their own company; sees its delivery log, sends a delivery again and tests routes. Gets the administration events by personal email |
| Every person of a company | Chooses their own personal emails in My profile |
An API token with the company admin role can change routes and the What is announced settings, but not the mail server, and cannot send the test email: those take a signed-in session.
Audit log
| Action | When |
|---|---|
update_company | The company's settings were saved, with what changed. Webhook URLs, signing secrets and the SMTP password are never shown |
notification_redelivered | Someone sent a delivery again (Send again) |
notification_route_tested | Someone sent a test to a route (Send test) |
smtp_test_sent | Someone sent a test email, with the server and, when it failed, why |
notification_failed | A delivery failed for good: the route or person, the event and the kind of failure |
notification_personal_skipped | Personal emails were not sent because the company has no mail server (once a day) |
notification_preferences_changed | A person changed their personal emails in My profile |
notification_unsubscribed | A person unsubscribed with the link of a personal email |
Sending a notification is not itself written to the audit log; the event behind it usually is (for example mr_merged_without_approval, job_failed or connection_unhealthy). See Audit log.
Related pages
- Channels: Slack, Teams, email and the mail server, field by field.
- Events: every event, when it is sent and what it says.
- Routes: routing, path patterns, Stop here and ordering.
- Personal notifications: emails to people, preferences and unsubscribe.
- Delivery log and failures: retries, the delivery log, failures and Send test.
- Outbound webhooks: payload and signature.
- Troubleshooting notifications: when something does not arrive.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →