- Requirements
- Accepted headers
- Rejected headers
- Set it up
- Troubleshooting
Incoming email
GitLab has several features based on receiving incoming email messages:
- Reply by Email: allow GitLab users to comment on issues and merge requests by replying to notification email.
- 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 email support to your customers through GitLab.
Requirements
We recommend using an email address that receives only messages that are intended for the GitLab instance. Any incoming email messages not intended for GitLab receive a reject notice.
Handling incoming email messages 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
ends 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.
Catch-all mailbox
A catch-all mailbox for a domain receives all email messages addressed to the domain that do not match any addresses that exist on the mail server.
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
To set up this solution, you must create a dedicated email address to receive your users’ replies to GitLab notifications. However, this method only supports replies, and not the other features of incoming email.
Accepted headers
- Accepting
Cc
headers introduced in GitLab 16.5. - Accepting
X-Original-To
headers introduced in GitLab 17.0. - Accepting
X-Forwarded-To
headers introduced in GitLab 17.6. - Accepting
X-Delivered-To
headers introduced in GitLab 17.6.
Email is processed correctly when a configured email address is present in one of the following headers (sorted in the order they are checked):
To
Delivered-To
X-Delivered-To
-
Envelope-To
orX-Envelope-To
Received
X-Original-To
X-Forwarded-To
Cc
The References
header is also accepted, however it is used specifically to relate email responses to existing discussion threads. It is not used for creating issues by email.
In GitLab 14.6 and later, Service Desk also checks accepted headers.
Usually, the To
field contains the email address of the primary receiver.
However, it might not include the configured GitLab email address if:
- The address is in the
BCC
field. - The email was forwarded.
The Received
header can contain multiple email addresses. These are checked in the order that they appear.
The first match is used.
Rejected headers
To prevent unwanted issue creation from automatic email systems, GitLab ignores all incoming email containing the following headers:
-
Auto-Submitted
with a value other thanno
-
X-Autoreply
with a value ofyes
Set it up
If you want to use Gmail / Google Apps for incoming email, 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
For example, suppose your top-level company domain is hooli.com
.
All employees in your company have an email address at that domain through Google
Workspace, 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 select 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.
FROM
address, which can cause the mail server’s IP or domain to appear on a block
list.Linux 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 # Needed when enabling or disabling for the first time but not for password changes. # See https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23560#note_61966788 sudo gitlab-ctl restart
-
Verify that everything is configured correctly:
sudo gitlab-rake gitlab:incoming_email:check
Reply by email should now be working.
Self-compiled installations
-
Go to the GitLab installation directory:
cd /home/git/gitlab
-
Install the
gitlab-mail_room
gem manually:gem install gitlab-mail_room
This step is necessary to avoid thread deadlocks and to support the latest MailRoom features. See this explanation for more details. -
Find the
incoming_email
section inconfig/gitlab.yml
, enable the feature and fill in the details for your specific IMAP server and email account (see examples below).
If you use systemd units to manage GitLab:
-
Add
gitlab-mailroom.service
as a dependency togitlab.target
:sudo systemctl edit gitlab.target
In the editor that opens, add the following and save the file:
[Unit] Wants=gitlab-mailroom.service
-
If you run Redis and PostgreSQL on the same machine, you should add a dependency on Redis. Run:
sudo systemctl edit gitlab-mailroom.service
In the editor that opens, add the following and save the file:
[Unit] Wants=redis-server.service After=redis-server.service
-
Start
gitlab-mailroom.service
:sudo systemctl start gitlab-mailroom.service
-
Verify that everything is configured correctly:
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
If you use the SysV init script to manage GitLab:
-
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 Linux package installations:
gitlab_rails['incoming_email_enabled'] = true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@gitlab.example.com.
# The placeholder 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
# If you are using Microsoft Graph instead of IMAP, set this to false to retain
# messages in the inbox because deleted messages are auto-expunged after some time.
gitlab_rails['incoming_email_delete_after_delivery'] = true
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
gitlab_rails['incoming_email_expunge_deleted'] = true
Example for self-compiled installations:
incoming_email:
enabled: true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@gitlab.example.com.
# The placeholder 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
# If you are using Microsoft Graph instead of IMAP, set this to false to retain
# messages in the inbox because deleted messages are auto-expunged after some time.
delete_after_delivery: true
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
expunge_deleted: true
Gmail
Example configuration for Gmail/Google Workspace. Assumes mailbox gitlab-incoming@gmail.com
.
incoming_email_email
cannot be a Gmail alias account.Example for Linux package installations:
gitlab_rails['incoming_email_enabled'] = true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@gmail.com.
# The placeholder 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
# If you are using Microsoft Graph instead of IMAP, set this to false if you want to retain
# messages in the inbox because deleted messages are auto-expunged after some time.
gitlab_rails['incoming_email_delete_after_delivery'] = true
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
gitlab_rails['incoming_email_expunge_deleted'] = true
Example for self-compiled installations:
incoming_email:
enabled: true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@gmail.com.
# The placeholder 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
# If you are using Microsoft Graph instead of IMAP, set this to falseto retain
# messages in the inbox because deleted messages are auto-expunged after some time.
delete_after_delivery: true
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
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 Linux package installations:
gitlab_rails['incoming_email_enabled'] = true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress-%{key}@exchange.example.com.
# The placeholder 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
# Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
gitlab_rails['incoming_email_expunge_deleted'] = true
Example for self-compiled installations:
incoming_email:
enabled: true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress-%{key}@exchange.example.com.
# The placeholder 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
# If you are using Microsoft Graph instead of IMAP, set this to false to retain
# messages in the inbox since deleted messages are auto-expunged after some time.
delete_after_delivery: true
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
expunge_deleted: true
Dedicated email address
Assumes the dedicated email address incoming@exchange.example.com
.
Example for Linux package installations:
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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true
Example for self-compiled installations:
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
# If you are using Microsoft Graph instead of IMAP, set this to false to retain
# messages in the inbox since deleted messages are auto-expunged after some time.
delete_after_delivery: true
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
expunge_deleted: true
Microsoft Office 365
Example configurations for Microsoft Office 365 with IMAP enabled.
Sub-addressing mailbox
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.
To enable sub-addressing:
- Download and install the
ExchangeOnlineManagement
module from the PowerShell gallery. -
In PowerShell, run the following commands:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser Import-Module ExchangeOnlineManagement Connect-ExchangeOnline Set-OrganizationConfig -AllowPlusAddressInRecipients $true Disconnect-ExchangeOnline
This example for Linux package installations 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. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@office365.example.com.
# The placeholder 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true
This example for self-compiled installations 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. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@office365.example.com.
# The placeholder 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
expunge_deleted: true
Catch-all mailbox
This example for Linux package installations 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. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress-%{key}@office365.example.com.
# The placeholder 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true
This example for self-compiled installations 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. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@office365.example.com.
# The placeholder 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
expunge_deleted: true
Dedicated email address
This example for Linux package installations 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
gitlab_rails['incoming_email_expunge_deleted'] = true
This example for self-compiled installations 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
# Whether to expunge (permanently remove) messages from the mailbox when they are marked as deleted after delivery
expunge_deleted: true
Microsoft Graph
GitLab can read incoming email using the Microsoft Graph API instead of IMAP. Because Microsoft is deprecating IMAP usage with Basic Authentication, the Microsoft Graph API is be required for new Microsoft Exchange Online mailboxes.
To configure GitLab for Microsoft Graph, you need to register an
OAuth 2.0 application in your Azure Active Directory that has the
Mail.ReadWrite
permission for all mailboxes. See the MailRoom step-by-step guide
and Microsoft instructions
for more details.
Record the following when you configure your OAuth 2.0 application:
- Tenant ID for your Azure Active Directory
- Client ID for your OAuth 2.0 application
- Client secret your OAuth 2.0 application
Restrict mailbox access
For MailRoom to work as a service account, the application you create
in Azure Active Directory requires that you set the Mail.ReadWrite
property
to read/write mail in all mailboxes.
To mitigate security concerns, we recommend configuring an application access policy which limits the mailbox access for all accounts, as described in Microsoft documentation.
This example for Linux package installations assumes you’re using the following mailbox: incoming@example.onmicrosoft.com
:
Configure Microsoft Graph
- Alternative Azure deployments introduced in GitLab 14.9.
gitlab_rails['incoming_email_enabled'] = true
# The email address including the %{key} placeholder that will be replaced to reference the
# item being replied to. This %{key} should be included in its entirety within the email
# address and not replaced by another value.
# For example: emailaddress+%{key}@example.onmicrosoft.com.
# The placeholder must appear in the "user" part of the address (before the `@`).
gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.onmicrosoft.com"
# Email account username
gitlab_rails['incoming_email_email'] = "incoming@example.onmicrosoft.com"
gitlab_rails['incoming_email_delete_after_delivery'] = false
gitlab_rails['incoming_email_inbox_method'] = 'microsoft_graph'
gitlab_rails['incoming_email_inbox_options'] = {
'tenant_id': '<YOUR-TENANT-ID>',
'client_id': '<YOUR-CLIENT-ID>',
'client_secret': '<YOUR-CLIENT-SECRET>',
'poll_interval': 60 # Optional
}
For Microsoft Cloud for US Government or other Azure deployments, configure the azure_ad_endpoint
and graph_endpoint
settings.
- Example for Microsoft Cloud for US Government:
gitlab_rails['incoming_email_inbox_options'] = {
'azure_ad_endpoint': 'https://login.microsoftonline.us',
'graph_endpoint': 'https://graph.microsoft.us',
'tenant_id': '<YOUR-TENANT-ID>',
'client_id': '<YOUR-CLIENT-ID>',
'client_secret': '<YOUR-CLIENT-SECRET>',
'poll_interval': 60 # Optional
}
The Microsoft Graph API is not yet supported in self-compiled installations. See this issue for more details.
Use encrypted credentials
- Introduced in GitLab 15.9.
Instead of having the incoming email credentials stored in plaintext in the configuration files, you can optionally use an encrypted file for the incoming email credentials.
Prerequisites:
- To use encrypted credentials, you must first enable the encrypted configuration.
The supported configuration items for the encrypted file are:
user
password
-
If initially your incoming email configuration in
/etc/gitlab/gitlab.rb
looked like:gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com" gitlab_rails['incoming_email_password'] = "examplepassword"
-
Edit the encrypted secret:
sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim
-
Enter the unencrypted contents of the incoming email secret:
user: 'incoming-email@mail.example.com' password: 'examplepassword'
- Edit
/etc/gitlab/gitlab.rb
and remove theincoming_email
settings foremail
andpassword
. -
Save the file and reconfigure GitLab:
sudo gitlab-ctl reconfigure
Use a Kubernetes secret to store the incoming email password. For more information, read about Helm IMAP secrets.
-
If initially your incoming email configuration in
docker-compose.yml
looked like:version: "3.6" services: gitlab: image: 'gitlab/gitlab-ee:latest' restart: always hostname: 'gitlab.example.com' environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['incoming_email_email'] = "incoming-email@mail.example.com" gitlab_rails['incoming_email_password'] = "examplepassword"
-
Get inside the container, and edit the encrypted secret:
sudo docker exec -t <container_name> bash gitlab-rake gitlab:incoming_email:secret:edit EDITOR=editor
-
Enter the unencrypted contents of the incoming email secret:
user: 'incoming-email@mail.example.com' password: 'examplepassword'
- Edit
docker-compose.yml
and remove theincoming_email
settings foremail
andpassword
. -
Save the file and restart GitLab:
docker compose up -d
-
If initially your incoming email configuration in
/home/git/gitlab/config/gitlab.yml
looked like:production: incoming_email: user: 'incoming-email@mail.example.com' password: 'examplepassword'
-
Edit the encrypted secret:
bundle exec rake gitlab:incoming_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
-
Enter the unencrypted contents of the incoming email secret:
user: 'incoming-email@mail.example.com' password: 'examplepassword'
- Edit
/home/git/gitlab/config/gitlab.yml
and remove theincoming_email:
settings foruser
andpassword
. -
Save the file and restart GitLab and Mailroom
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
Troubleshooting
Email ingestion doesn’t work in 16.6.0
GitLab self-managed 16.6.0
introduced a regression that prevents mail_room
(email ingestion) from starting.
Service Desk and other reply-by-email features don’t work.
Issue 432257 tracks fixing this problem.
The workaround is to run the following commands in your GitLab installation to patch the affected files:
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch
gitlab-ctl restart mailroom
curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff"
cd /opt/gitlab/embedded/service/gitlab-rails
patch -p1 < /tmp/mailroom.patch
gitlab-ctl restart mailroom
Incoming emails are rejected by providers with email address limit
Your GitLab instance might not receive incoming emails, because some email providers impose a
64-character limit on the local part of the email address (before the @
).
All emails from addresses that exceed this limit are rejected emails.
As a workaround, maintain a shorter path:
- Ensure that the local part configured before
%{key}
inincoming_email_address
is as short as possible, and not longer than 31 characters. - Place the designated projects at a higher group hierarchy.
- Rename groups and project to shorter names.
Track this feature in issue 460206.