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:
| Channel | Fields | The route counts as configured when |
|---|---|---|
| Slack, Teams | Webhook URL | A webhook URL is saved |
| Recipients | It has at least one recipient | |
| Webhook | Signing secret, Webhook URL | A 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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Webhook URL | The 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 one | Empty | The webhook URL Slack or Teams gave you | Company admin, platform admin | notifications.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
| Slack | Teams | |
|---|---|---|
| Form | A message with one attachment; the notification's title is also the plain text that notifications and previews show | An Adaptive Card (version 1.2) |
| Title | The event's title, bold, linking to the page in Merge Pilot | The event's title, bold |
| Colour | A bar: green, amber or red by the event (see Events) | The title's colour: good, warning or attention |
| Text | The event's message, then Open in Merge Pilot · Notification settings | The event's message |
| Links | In the text | Buttons: Open in Merge Pilot and Notification settings |
| Footer | Merge Pilot · <company>. You get this because … and the time | Merge 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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Recipients | Email 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 below | Empty | Plain 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 admin | notifications.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
5xxreply, such as an unknown mailbox) is not tried again for that recipient. A temporary failure (a4xxreply, 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
4xxreply, no answer, a broken connection) is retried like any failure. - A permanent one (a
5xxreply 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 does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Host | The mail server's host name or IP address | Empty | A host name, such as smtp.example.com | Company admin, platform admin (signed-in session) | smtp.host |
| Port | The mail server's port. Usually 587 (STARTTLS), 465 (implicit TLS) or 25. Any port from 1 to 65535. | 587 | 1 to 65535 | Company admin, platform admin (signed-in session) | smtp.port |
| TLS mode | How the connection is encrypted. See TLS mode | STARTTLS (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 mode | How Merge Pilot signs in to the mail server. See Auth mode | PLAIN | PLAIN, LOGIN, CRAM-MD5, None (no auth) | Company admin, platform admin (signed-in session) | smtp.auth_mode: plain, login, cram-md5, none |
| Username | The account Merge Pilot signs in with; required with authentication. Hidden when Auth mode is None (no auth) | Empty | Any text | Company admin, platform admin (signed-in session) | smtp.username |
| Password | The 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. | Empty | Any text | Company 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. | Empty | One or more PEM certificates | Company admin, platform admin (signed-in session) | smtp.ca_certificate |
| From address | The sender address of every notification email; required | Empty | A plain email address, such as noreply@example.com | Company admin, platform admin (signed-in session) | smtp.from_address |
| From name | The sender name shown next to the address | Empty (the address alone) | One line, at most 100 characters | Company 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.1or::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
STARTTLSbefore 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.routesis the whole list of routes, in order; see Routes → API.smtpis one object with the fields above. Sendingsmtpwith an emptypasswordkeeps the saved one for the samehost,port,username,tls_mode,auth_modeandca_certificate, and removes it otherwise.{"smtp": {"host": ""}}removes the mail server; while the company has email routes this is a400(invalid input: email routes need the mail server: remove them before the mail server). API tokens cannot changesmtp: the answer is403(API tokens cannot change smtp: use a signed-in session).- Secrets are never returned:
webhook_url,secretandsmtp.passwordare write-only, and the answers carryhas_webhook_url,has_secretandsmtp.has_passwordinstead.
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.
Related pages
- Notifications: what is sent and where.
- Routes: which events go to which channel.
- Delivery log and failures: retries and the delivery history.
- Personal notifications: emails to people.
- Outbound webhooks: the webhook channel.
- Events: titles, messages and colours.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →