Configure GitLab incoming e-mails

In many DevOps workflows, the integration of email systems is an essential part of automated communication. GitLab offers the possibility to process incoming emails - for example to create issues or comments directly via email. This can be particularly useful in environments with a high level of automation or when integrating existing support systems.

Requirements

• GitLab Server
• E-mail sub-address (recommended) or catch-all mailbox
• Optional: Protected domain (creoline E-Mail-Protection)

E-mail subaddressing

Email subaddressing allows you to add additional identifiers to an existing email address without creating new mailboxes. If e-mail subaddressing is supported, e-mails for incoming@mail.creoline.de can also be sent to them via incoming+addon@mail.creoline.de, for example.

Security note on the domain used

https://docs.gitlab.com/ee/administration/incoming_email.html#security-concerns

Preparation of your DNS zone

Create the following DNS records in your DNS zone:

RR type: A
Host: mail
Value: <your Plesk server IPv4>
TTL: 3600

RR type: AAAA
Host: mail
Value: <your Plesk server IPv6>
TTL: 3600

RR type: MX
Host: mail
Value: mail.creoline-demo.de
TTL: 3600

Preparation e-mail domain (example: Plesk server)

For security reasons, it is not advisable to use the external domain via which your Web UI is accessed, which is why a subdomain of the external domain should be used as the e-mail domain or always a different one.

Create Plesk domain

Create a domain in Plesk which is to be used for incoming emails. There are no practical restrictions here, the following example uses the subdomain mail.creoline-demo.de.

Create Plesk e-mail mailbox

After you have created your e-mail domain, create an e-mail mailbox, for example: incoming.

Customize GitLab configuration file

The adjustments must only be made in the gitlab.rb, which you can find and edit in the configuration files of your GitLab server.

The following settings must be adjusted or commented out in gitlab.rb if a completely custom definition is made.

Activate incoming e-mails

gitlab_rails['incoming_email_enabled'] = true

Set incoming e-mail address

The 'incoming' mailbox must have been created accordingly with your e-mail provider.

gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com"

Set incoming e-mail addresses e-mail

gitlab_rails['incoming_email_email'] = "incoming" # customize if other mailbox was used

Set incoming e-mail address password

gitlab_rails['incoming_email_password'] = "<mailbox-password>"

Incoming e-mail port (encrypted, recommended)

SSL/TLS

 gitlab_rails['incoming_email_port'] = 993
 gitlab_rails['incoming_email_ssl'] = false
 gitlab_rails['incoming_email_start_tls'] = true

STARTTLS

 gitlab_rails['incoming_email_port'] = 143
 gitlab_rails['incoming_email_ssl'] = false
 gitlab_rails['incoming_email_start_tls'] = true

Incoming e-mail port (unencrypted, not recommended)

For SSL encryption, IMAP port 993 should be selected here, without encryption IMAP port 143.

 gitlab_rails['incoming_email_port'] = 143
 gitlab_rails['incoming_email_ssl'] = false
 gitlab_rails['incoming_email_start_tls'] = false

Complete example

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'] = "<mailbox-password>"

# IMAP server host
gitlab_rails['incoming_email_host'] = "gitlab.example.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

Reconfigure GitLab

sudo gitlab-ctl reconfigure

Test incoming e-mails

sudo gitlab-rake gitlab:incoming_email:check
Checking Incoming Email ...

Incoming Email: ... Checking Reply by email ...

IMAP server credentials are correct? ... Checking incoming@mail.creoline-demo.de
yes
Mailroom enabled? ... skipped
MailRoom running? ... skipped

Checking Reply by email ... Finished

<br>

Checking Incoming Email ... Finished