Skip to main content
Video tutorial · 0:51

Channels

A channel is where a notification route sends its events: a Slack or Microsoft Teams channel, a list of email addresses, or your own HTTP endpoint. This page describes what each channel needs, what its messages contain and how they are sent. Which events a route takes is described in Routes; emails to the people an event concerns in Personal notifications.

Company page → Notifications. Company admins of the company and platform admins change these settings; they are saved with Save changes (see Saving). None of them is held for four-eyes review.

Choosing the channel of a route​

Each route has a Channel select: Slack (the default for a new route), Teams, Email or Webhook. The fields below the select follow the channel:

ChannelFieldsThe route counts as configured when
Slack, TeamsWebhook URLA webhook URL is saved
EmailRecipientsIt has at least one recipient
WebhookSigning secret, Webhook URLA webhook URL is saved

The route's header shows a dot: green with the tooltip Channel configured, amber with Channel not configured. A route cannot be saved without its channel's fields: Slack, Teams and webhook routes need a webhook URL, email routes at least one recipient and the company's mail server (see Routes → API for the messages).

Message content​

Slack, Teams and email show the same message, built from the event (every event's title and message are on Events):

  • Title: one line, cut at 120 characters (the last one … when cut).
  • Message: its line breaks kept, cut at 2,000 characters.
  • Open in Merge Pilot: a link to the page the event is about (the merge request, the change approval in the built-in tracker, the project, the vulnerability inventory, the jobs page or a tab of the company page). Left out when Merge Pilot's own address is not set in the platform settings.
  • Footer: Merge Pilot · <company name>, then why the reader gets it: You get this because the notification route “<route name>” takes this event (a personal email names the person's own reason, see One email per person), and Notification settings, a link to the company's Notifications tab (My profile → Notifications for a personal email). Then the time, in UTC.

Names stay text. Messages include text from your VCS and tracker: merge request titles, branch, project and user names. That text can never mention people or channels (such as <!channel> in Slack) or make a link with a label of its own (a disguised link). Formatting characters in it (bold, italic, strike-through, code) are neutralized so they show as written. A bare web address stays as written, and Slack or Teams may still show it as a link. Only the message's own Open in Merge Pilot and Notification settings links are links.

Slack and Teams​

Both post to a channel through a webhook that you create in Slack or Teams for that channel:

  • Slack: an incoming webhook of a Slack app.
  • Teams: a Workflows webhook, made with the workflow template that posts to a channel when a webhook request is received. (Microsoft retired the older Office 365 connectors' incoming webhooks.)
Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
Webhook URLThe webhook the route posts to. It carries a secret of its own, so it is write-only: the field stays empty (Leave empty to keep current) and a badge shows Configured or Not configured. Typing a new URL replaces the saved oneEmptyThe webhook URL Slack or Teams gave youCompany admin, platform adminnotifications.routes[].webhook_url (write-only); has_webhook_url in answers

When saved, the URL must start with http:// or https://. When a message is sent, Merge Pilot refuses a URL whose host resolves to a private network address (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7), a loopback, link-local or cloud metadata address: Slack and Teams webhooks are internet services. Such an attempt fails with the webhook's host "<host>" resolves to an address that is not allowed; the URL itself is never shown.

What a message looks like​

SlackTeams
FormA message with one attachment; the notification's title is also the plain text that notifications and previews showAn Adaptive Card (version 1.2)
TitleThe event's title, bold, linking to the page in Merge PilotThe event's title, bold
ColourA bar: green, amber or red by the event (see Events)The title's colour: good, warning or attention
TextThe event's message, then Open in Merge Pilot · Notification settingsThe event's message
LinksIn the textButtons: Open in Merge Pilot and Notification settings
FooterMerge Pilot · <company>. You get this because … and the timeMerge Pilot · <company>. You get this because … · <date and time in UTC>

A Slack message counts as sent only when Slack answers 200; a Teams message when Teams answers any 2xx. A Teams message is shortened further, should it be larger than Teams accepts.

Email​

An email route sends each event to a list of addresses through the company's own mail server, set in SMTP configuration on the same tab. An email route cannot be saved while the company has no mail server: the route shows Set up the mail server below first: an email route cannot be saved without it, and while there is none, email routes are skipped (the other routes still get their events)., and saving is refused. Should the mail server be gone when an event is sent, the email route is skipped and the other routes still get the event.

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
RecipientsEmail addresses to send notifications to. Requires SMTP to be configured below. Type an address and press Enter (email@example.com then Enter); each address shows as a chip with a remove button. Addresses of deactivated people are named in a warning belowEmptyPlain email addresses, such as ops@example.com (not Ops <ops@example.com>); at least one. The part before @ must be plain ASCII; the domain may be internationalized (see Internationalized domains)Company admin, platform adminnotifications.routes[].recipients (list of strings)

What an email looks like​

  • Subject: [Merge Pilot] <the event's title>; a title with characters outside plain ASCII is encoded so every mail program shows it.
  • From: the From name and From address below.
  • To: only the recipient's own address: recipients never see each other.
  • Body: two versions of the same content, which the mail program chooses from: plain text, and HTML with a coloured bar (green, amber or red by the event), the title, the message, an Open in Merge Pilot button and the footer. All text is shown as it is: names from the VCS cannot add HTML or links.
  • Headers: a date, a unique message ID, and a mark that the email was sent automatically (so out-of-office replies are not sent back). A personal email also carries the one-click unsubscribe headers (see Unsubscribe).

How email is sent​

  • One message per recipient. Each recipient gets their own copy, all within one connection to the mail server.
  • One refused address does not stop the others. A recipient the mail server refuses is recorded, and the others still get the message.
  • Permanent and temporary failures. A permanent refusal (a 5xx reply, such as an unknown mailbox) is not tried again for that recipient. A temporary failure (a 4xx reply, no answer, a broken connection) is retried, to the recipients that failed only: those that accepted the message do not get it twice. The delivery shows Delivered to N recipients: and Refused for good by N recipients: (see Delivery log and failures).
  • Time limit. Each attempt has a time limit, longer for more recipients; recipients not reached in time are retried. A mail server that does not answer cannot hold up other notifications.
  • After acceptance. Once the mail server accepted a message, it counts as delivered even if the connection breaks afterwards: it is never sent twice for that.
  • A broken session after a refusal. When the mail server refuses one recipient and the connection then breaks, or the server refuses to reset for the next recipient, the recipients not reached yet fail temporarily and are retried. They are never counted as refused because of the earlier recipient's refusal.

Mail server problems are not refusals​

Some failures are about the mail server or its settings, not about a recipient: Merge Pilot cannot connect, the TLS handshake fails, the server does not offer STARTTLS, the sign-in is refused (for example 535, wrong password), or the server refuses the from address. Then no recipient is counted as Refused for good; the recipients not reached yet are tried again on the next attempt. The attempt's error starts with the mail server could not be used: and names the step and the reason.

  • A temporary problem (a 4xx reply, no answer, a broken connection) is retried like any failure.
  • A permanent one (a 5xx reply such as a refused sign-in, or settings Merge Pilot refuses) fails the delivery at once, without retries. Its kind of failure is the mail server refused its settings or sign-in; when temporary problems last through every attempt, it is the mail server could not be used, even after retries.

Fix the settings in SMTP configuration, check them with Send test email, then Send again the failed deliveries.

Internationalized domains​

A domain with characters outside plain ASCII, such as şirket.com.tr, is sent in its ASCII form (xn--irket-idb.com.tr): in the from address, the recipients' addresses, the server greeting and the message ID. The settings and the delivery log keep the addresses as you typed them. The part of an address before @ must be plain ASCII: an address such as çağrı@example.com is refused when the route or the mail server is saved, and a person with such an address gets no personal emails.

Merge Pilot's own address, when its host name is internationalized, appears in the same ASCII form in the links of every email (Open in Merge Pilot, the unsubscribe links and the one-click unsubscribe header).

SMTP configuration​

SMTP settings for email notifications. Required for routes with the Email channel. Clear the host and save to remove the mail server (remove the email routes first). One mail server per company; it sends the email routes' messages and the personal emails.

When the Password field is left empty, the saved password is kept only if Host, Port, Username, TLS mode, Auth mode and CA certificate stay as saved. Changing any of them without typing the password again removes the saved password: it is never sent to another server, over another kind of connection, or to a server another certificate authority vouches for.

Clearing Host and saving removes the mail server. While the company has email routes, this is refused: remove them first (or in the same save).

Setting (label in the UI)What it doesDefaultAllowed valuesWho can change itAPI field
HostThe mail server's host name or IP addressEmptyA host name, such as smtp.example.comCompany admin, platform admin (signed-in session)smtp.host
PortThe mail server's port. Usually 587 (STARTTLS), 465 (implicit TLS) or 25. Any port from 1 to 65535.5871 to 65535Company admin, platform admin (signed-in session)smtp.port
TLS modeHow the connection is encrypted. See TLS modeSTARTTLS (port 587)STARTTLS (port 587), Implicit TLS (port 465), None (port 25)Company admin, platform admin (signed-in session)smtp.tls_mode: starttls, tls, none
Auth modeHow Merge Pilot signs in to the mail server. See Auth modePLAINPLAIN, LOGIN, CRAM-MD5, None (no auth)Company admin, platform admin (signed-in session)smtp.auth_mode: plain, login, cram-md5, none
UsernameThe account Merge Pilot signs in with; required with authentication. Hidden when Auth mode is None (no auth)EmptyAny textCompany admin, platform admin (signed-in session)smtp.username
PasswordThe account's password. Write-only: the field stays empty (Leave empty to keep current) and a badge shows Configured or Not configured. Hidden when Auth mode is None (no auth). Gmail and Google Workspace: use an app password, which needs 2-Step Verification. Google refuses account passwords over SMTP since March 14, 2025.EmptyAny textCompany admin, platform admin (signed-in session)smtp.password (write-only); has_password in answers
CA certificate (optional)PEM. Trusted besides the system CAs: for a mail server whose certificate your own CA issued.EmptyOne or more PEM certificatesCompany admin, platform admin (signed-in session)smtp.ca_certificate
From addressThe sender address of every notification email; requiredEmptyA plain email address, such as noreply@example.comCompany admin, platform admin (signed-in session)smtp.from_address
From nameThe sender name shown next to the addressEmpty (the address alone)One line, at most 100 charactersCompany admin, platform admin (signed-in session)smtp.from_name

The ports in the labels are the usual ones for each mode; the Port field is not changed by choosing a mode.

The settings are checked before they are saved, in the form (its message shows under the field) and again by the save itself (400, invalid input: smtp: …). They are refused when:

  • the port is outside 1 to 65535;
  • an auth mode is chosen with None (port 25) and the host is not localhost, 127.0.0.1 or ::1 (form: Authentication needs TLS: choose STARTTLS or implicit TLS, or set the auth mode to None.);
  • an auth mode is chosen without a user name (form: Authentication needs a username.);
  • the from address is missing or not a plain address (form: The from address is required., Enter a plain email address, such as noreply@example.com.), or the part before @ is not plain ASCII;
  • the from name is longer than 100 characters or has line breaks;
  • the CA certificate is not a PEM certificate;
  • the host contains spaces or other characters a host name cannot have.

TLS mode​

  • STARTTLS (port 587): connects unencrypted and switches to TLS with STARTTLS before signing in. Sending fails if the server does not offer it (the mail server does not offer STARTTLS): Merge Pilot never falls back to an unencrypted connection.
  • Implicit TLS (port 465): the connection is TLS from the start.
  • None (port 25): no encryption.

With TLS, the server's certificate must be valid for the Host and trusted: by the system's certificate authorities, or by the CA certificate you set. TLS 1.2 or later.

Auth mode​

The password is sent only over TLS (STARTTLS or implicit TLS); without TLS only to localhost, 127.0.0.1 or ::1.

  • PLAIN: user name and password.
  • LOGIN: user name and password, for servers that offer only LOGIN.
  • CRAM-MD5: a challenge-response; the password itself is not sent, but the same TLS rule applies.
  • None (no auth): the server accepts mail without signing in, such as an internal relay.

Sending fails when the server does not offer authentication while an auth mode is set (the mail server does not offer authentication).

Send test email​

Send test email (enabled once Host is filled in) sends a test message, [Merge Pilot] SMTP test, to your own email address, using the settings as the form shows them, not yet saved. It takes at most 20 seconds. The result shows under the card's description:

  • test email sent to <address> when the server accepted it;
  • sending failed: <host>:<port>: <step>: <reason> when it did not. The step is where it failed (connect, TLS, greeting, EHLO, STARTTLS, authentication, MAIL FROM, RCPT TO, DATA, settings); the reason is the mail server's own reply (the mail server answered 535 …) or what went wrong, by kind only: the mail server's host name could not be resolved, the mail server refused the connection, the mail server did not answer in time, the mail server closed the connection, the mail server could not be reached, the mail server's address is not allowed, the mail server's TLS certificate is not trusted, the TLS handshake with the mail server failed, the server did not answer as a mail server;
  • set the SMTP host first when there is no host;
  • the settings checks above, when a setting is not allowed;
  • your account does not have an email address configured when your user has no email address.

When the Password field is empty, the test uses the saved password only if the settings it depends on are those saved (see above). Changing any of them means typing the password again for the test.

The test is available only in a signed-in session (not with an API token). Each test is written to the audit log as smtp_test_sent, with the server and, for a failure, its reason.

The reason is detailed on purpose, so you can fix the settings: it tells whether the host name resolved, whether the port answered, and whether the certificate is trusted. This means a company admin can learn from it whether a host and port can be reached from where Merge Pilot runs. The raw network error, which can name internal addresses, is never shown.

Webhook​

A Webhook route posts each event as signed JSON to your own endpoint. Its fields (Signing secret, Webhook URL) are described in Outbound webhooks.

API​

The channels are part of the company: GET /api/v1/companies/{id} returns notifications.routes and smtp; PUT /api/v1/companies/{id} changes them (see Company API).

  • notifications.routes is the whole list of routes, in order; see Routes → API.
  • smtp is one object with the fields above. Sending smtp with an empty password keeps the saved one for the same host, port, username, tls_mode, auth_mode and ca_certificate, and removes it otherwise. {"smtp": {"host": ""}} removes the mail server; while the company has email routes this is a 400 (invalid input: email routes need the mail server: remove them before the mail server). API tokens cannot change smtp: the answer is 403 (API tokens cannot change smtp: use a signed-in session).
  • Secrets are never returned: webhook_url, secret and smtp.password are write-only, and the answers carry has_webhook_url, has_secret and smtp.has_password instead.

POST /api/v1/companies/{id}/test-smtp sends the test email (company admins, platform admins, signed-in session). Its body is optional: {"smtp": {...}} tests those settings, an empty body the saved ones. It answers 200 with success (true when the server accepted the message) and message in data; a missing host, a setting that is not allowed or a user without an email address is a 400.

Video tutorial

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 ↗