Skip to main content
2 video tutorials

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 goesSet up with
SlackA Slack channel, as a message with a coloured barThe channel's Slack incoming webhook URL
TeamsA Microsoft Teams channel, as an Adaptive CardThe channel's Teams Workflows webhook URL
EmailA list of email addresses, one message eachThe company's mail server (SMTP configuration) and the recipients
WebhookYour own HTTP endpoint, as signed JSONAn http(s):// URL and a signing secret
Personal emailThe people an event concerns: a change approval's assignee, a merge request's author, the company adminsThe 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:

  1. a red banner when deliveries failed in the last 7 days, with Show failed deliveries;
  2. What is announced: the company-wide switches;
  3. Notification routes: the routes, in order, each with Send test and Recent deliveries;
  4. SMTP configuration: the mail server for email routes and personal emails, with Send test email;
  5. 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​

RoleNotifications
Platform adminSets up the notifications of any company; sees its deliveries
Company adminSets 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 companyChooses 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​

ActionWhen
update_companyThe company's settings were saved, with what changed. Webhook URLs, signing secrets and the SMTP password are never shown
notification_redeliveredSomeone sent a delivery again (Send again)
notification_route_testedSomeone sent a test to a route (Send test)
smtp_test_sentSomeone sent a test email, with the server and, when it failed, why
notification_failedA delivery failed for good: the route or person, the event and the kind of failure
notification_personal_skippedPersonal emails were not sent because the company has no mail server (once a day)
notification_preferences_changedA person changed their personal emails in My profile
notification_unsubscribedA 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.

Video tutorials

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Notifications for the Right PeopleYouTube ↗
Send Events to Your Own Systems with Signed WebhooksYouTube ↗