Incoming email

GitLab has several features based on receiving incoming emails:

Reply by Email: allow GitLab users to comment on issues and merge requests by replying to notification emails.
New issue by email: allow GitLab users to create a new issue by sending an email to a user-specific email address.
New merge request by email: allow GitLab users to create a new merge request by sending an email to a user-specific email address.
Service Desk: provide e-mail support to your customers through GitLab.

Requirements

NOTE: Note: It is not recommended to use an email address that receives or will receive any messages not intended for the GitLab instance. Any incoming emails not intended for GitLab will receive a reject notice.

Handling incoming emails requires an IMAP-enabled email account. GitLab requires one of the following three strategies:

Email sub-addressing (recommended)
Catch-all mailbox
Dedicated email address (supports Reply by Email only)

Let's walk through each of these options.

Email sub-addressing

Sub-addressing is a mail server feature where any email to user+arbitrary_tag@example.com will end up in the mailbox for user@example.com . It is supported by providers such as Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the Postfix mail server, which you can run on-premises. Microsoft Exchange Server does not support sub-addressing, and Microsoft Office 365 does not support sub-addressing by default

TIP: Tip: If your provider or server supports email sub-addressing, we recommend using it. A dedicated email address only supports Reply by Email functionality. A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7, but sub-addressing is still preferred because only one email address is used, leaving a catch-all available for other purposes beyond GitLab.

Catch-all mailbox

A catch-all mailbox for a domain receives all emails addressed to the domain that do not match any addresses that exist on the mail server.

As of GitLab 11.7, catch-all mailboxes support the same features as email sub-addressing, but email sub-addressing remains our recommendation so that you can reserve your catch-all mailbox for other purposes.

Dedicated email address

This solution is relatively simple to set up: you just need to create an email address dedicated to receive your users' replies to GitLab notifications. However, this method only supports replies, and not the other features of incoming email.

Set it up

If you want to use Gmail / Google Apps for incoming emails, make sure you have IMAP access enabled and allowed less secure apps to access the account or turn-on 2-step validation and use an application password.

If you want to use Office 365, and two-factor authentication is enabled, make sure you're using an app password instead of the regular password for the mailbox.

To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the Postfix setup documentation.

Security concerns

CAUTION: Caution: Be careful when choosing the domain used for receiving incoming email.

For example, suppose your top-level company domain is hooli.com. All employees in your company have an email address at that domain via Google Apps, and your company's private Slack instance requires a valid @hooli.com email address to sign up.

If you also host a public-facing GitLab instance at hooli.com and set your incoming email domain to hooli.com, an attacker could abuse the "Create new issue by email" or "Create new merge request by email" features by using a project's unique address as the email when signing up for Slack. This would send a confirmation email, which would create a new issue or merge request on the project owned by the attacker, allowing them to click the confirmation link and validate their account on your company's private Slack instance.

We recommend receiving incoming email on a subdomain, such as incoming.hooli.com, and ensuring that you do not employ any services that authenticate solely based on access to an email domain such as *.hooli.com. Alternatively, use a dedicated domain for GitLab email communications such as hooli-gitlab.com.

See GitLab issue #30366 for a real-world example of this exploit.

CAUTION: Caution: Use a mail server that has been configured to reduce spam. A Postfix mail server that is running on a default configuration, for example, can result in abuse. All messages received on the configured mailbox will be processed and messages that are not intended for the GitLab instance will receive a reject notice. If the sender's address is spoofed, the reject notice will be delivered to the spoofed FROM address, which can cause the mail server's IP or domain to appear on a block list.

Omnibus package installations

Find the incoming_email section in /etc/gitlab/gitlab.rb, enable the feature and fill in the details for your specific IMAP server and email account (see examples below).

Reconfigure GitLab for the changes to take effect:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Verify that everything is configured correctly:
```
sudo gitlab-rake gitlab:incoming_email:check
```

Reply by email should now be working.

Installations from source

Go to the GitLab installation directory:
```
cd /home/git/gitlab
```
Find the incoming_email section in config/gitlab.yml, enable the feature and fill in the details for your specific IMAP server and email account (see examples below).

Enable mail_room in the init script at /etc/default/gitlab:

sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab

Restart GitLab:
```
sudo service gitlab restart
```

Verify that everything is configured correctly:

sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production

Reply by email should now be working.

Configuration examples

Postfix

Example configuration for Postfix mail server. Assumes mailbox incoming@gitlab.example.com.

Example for Omnibus installs:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"

# Email account username
# With third party providers, this is usually the full email address.
# With self-hosted email servers, this is usually the user part of the email address.
gitlab_rails['incoming_email_email'] = "incoming"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "gitlab.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 143
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = false
# Whether the IMAP server uses StartTLS
gitlab_rails['incoming_email_start_tls'] = false

# The mailbox where incoming mail will end up. Usually "inbox".
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60

# Whether to expunge (permanently remove) messages from the mailbox when they are deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true

Example for source installs:

incoming_email:
    enabled: true

    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
    address: "incoming+%{key}@gitlab.example.com"

    # Email account username
    # With third party providers, this is usually the full email address.
    # With self-hosted email servers, this is usually the user part of the email address.
    user: "incoming"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "gitlab.example.com"
    # IMAP server port
    port: 143
    # Whether the IMAP server uses SSL
    ssl: false
    # Whether the IMAP server uses StartTLS
    start_tls: false

    # The mailbox where incoming mail will end up. Usually "inbox".
    mailbox: "inbox"
    # The IDLE command timeout.
    idle_timeout: 60

    # Whether to expunge (permanently remove) messages from the mailbox when they are deleted after delivery
    expunge_deleted: true

Gmail

Example configuration for Gmail/G Suite. Assumes mailbox gitlab-incoming@gmail.com.

NOTE: Note: incoming_email_email cannot be a Gmail alias account.

Example for Omnibus installs:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com"

# Email account username
# With third party providers, this is usually the full email address.
# With self-hosted email servers, this is usually the user part of the email address.
gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "imap.gmail.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true
# Whether the IMAP server uses StartTLS
gitlab_rails['incoming_email_start_tls'] = false

# The mailbox where incoming mail will end up. Usually "inbox".
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
# The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60

# Whether to expunge (permanently remove) messages from the mailbox when they are deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true

Example for source installs:

incoming_email:
    enabled: true

    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
    address: "gitlab-incoming+%{key}@gmail.com"

    # Email account username
    # With third party providers, this is usually the full email address.
    # With self-hosted email servers, this is usually the user part of the email address.
    user: "gitlab-incoming@gmail.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "imap.gmail.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true
    # Whether the IMAP server uses StartTLS
    start_tls: false

    # The mailbox where incoming mail will end up. Usually "inbox".
    mailbox: "inbox"
    # The IDLE command timeout.
    idle_timeout: 60

    # Whether to expunge (permanently remove) messages from the mailbox when they are deleted after delivery
    expunge_deleted: true

Microsoft Exchange Server

Example configurations for Microsoft Exchange Server with IMAP enabled. Because Exchange does not support sub-addressing, only two options exist:

Catch-all mailbox (recommended for Exchange-only)
Dedicated email address (supports Reply by Email only)

Catch-all mailbox

Assumes the catch-all mailbox incoming@exchange.example.com.

Example for Omnibus installs:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
# Exchange does not support sub-addressing, so a catch-all mailbox must be used.
gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

Example for source installs:

incoming_email:
    enabled: true

    # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
    # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
    # Exchange does not support sub-addressing, so a catch-all mailbox must be used.
    address: "incoming-%{key}@exchange.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "exchange.example.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

Dedicated email address

Assumes the dedicated email address incoming@exchange.example.com.

Example for Omnibus installs:

gitlab_rails['incoming_email_enabled'] = true

# Exchange does not support sub-addressing, and we're not using a catch-all mailbox so %{key} is not used here
gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "exchange.example.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

Example for source installs:

incoming_email:
    enabled: true

    # Exchange does not support sub-addressing,
    # and we're not using a catch-all mailbox so %{key} is not used here
    address: "incoming@exchange.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "exchange.example.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

Microsoft Office 365

Example configurations for Microsoft Office 365 with IMAP enabled.

Sub-addressing mailbox

NOTE: Note: As of September 2020 sub-addressing support has been added to Office 365. This feature is not enabled by default, and must be enabled through PowerShell.

This series of PowerShell commands enables sub-addressing at the organization level in Office 365. This allows all mailboxes in the organization to receive sub-addressed mail:

NOTE: Note: This series of commands will enable sub-addressing at the organization level in Office 365. This will allow all mailboxes in the organization to receive sub-addressed mail.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

$UserCredential = Get-Credential

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

Import-PSSession $Session -DisableNameChecking

Set-OrganizationConfig -AllowPlusAddressInRecipients $true

This example for Omnibus GitLab assumes the mailbox incoming@office365.example.com:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the `%{key}` placeholder that will be replaced
# to reference the item being replied to. The placeholder can be omitted, but if
# present, it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@office365.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

This example for source installs assumes the mailbox incoming@office365.example.com:

incoming_email:
    enabled: true

    # The email address including the `%{key}` placeholder that will be replaced
    # to reference the item being replied to. The placeholder can be omitted, but
    # if present, it must appear in the "user" part of the address (before the `@`).
    address: "incoming+%{key}@office365.example.comm"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@office365.example.comm"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "outlook.office365.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

Catch-all mailbox

This example for Omnibus installs assumes the catch-all mailbox incoming@office365.example.com:

gitlab_rails['incoming_email_enabled'] = true

# The email address including the `%{key}` placeholder that will be replaced to
# reference the item being replied to. The placeholder can be omitted, but if present,
# it must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming-%{key}@office365.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

This example for source installs assumes the catch-all mailbox incoming@office365.example.com:

incoming_email:
    enabled: true

    # The email address including the `%{key}` placeholder that will be replaced
    # to reference the item being replied to. The placeholder can be omitted, but
    # if present, it must appear in the "user" part of the address (before the `@`).
    address: "incoming-%{key}@office365.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@ad-domain.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "outlook.office365.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true

Dedicated email address

This example for Omnibus installs assumes the dedicated email address incoming@office365.example.com:

gitlab_rails['incoming_email_enabled'] = true

gitlab_rails['incoming_email_address'] = "incoming@office365.example.com"

# Email account username
# Typically this is the userPrincipalName (UPN)
gitlab_rails['incoming_email_email'] = "incoming@office365.example.com"
# Email account password
gitlab_rails['incoming_email_password'] = "[REDACTED]"

# IMAP server host
gitlab_rails['incoming_email_host'] = "outlook.office365.com"
# IMAP server port
gitlab_rails['incoming_email_port'] = 993
# Whether the IMAP server uses SSL
gitlab_rails['incoming_email_ssl'] = true

This example for source installs assumes the dedicated email address incoming@office365.example.com:

incoming_email:
    enabled: true

    address: "incoming@office365.example.com"

    # Email account username
    # Typically this is the userPrincipalName (UPN)
    user: "incoming@office365.example.com"
    # Email account password
    password: "[REDACTED]"

    # IMAP server host
    host: "outlook.office365.com"
    # IMAP server port
    port: 993
    # Whether the IMAP server uses SSL
    ssl: true