doc/user/project/service_desk/configure.md
{{< details >}}
{{< /details >}}
By default, Service Desk is active in new projects. If it's not active, you can do it in the project's settings.
Prerequisites:
To enable Service Desk in your project:
Service Desk is now enabled for this project. If anyone sends an email to the address available below Email address to use for Service Desk, GitLab creates a confidential ticket with the email's content.
This glossary provides definitions for terms related to Service Desk.
| Term | Definition |
|---|---|
| External participant | Users without a GitLab account that can interact with an issue or Service Desk ticket only by email. |
| Requester | External participant that created the Service Desk ticket or was added as requester using the /convert_to_ticket quick action. |
To improve your Service Desk project's security, you should:
{{< history >}}
UNSUBSCRIBE_URL, SYSTEM_HEADER, SYSTEM_FOOTER, and ADDITIONAL_TEXT placeholders introduced in GitLab 15.9.%{ISSUE_DESCRIPTION} introduced in GitLab 16.0.%{ISSUE_URL} introduced in GitLab 16.1.{{< /history >}}
An email is sent to external participants when:
You can customize the body of these email messages with Service Desk email templates. The templates can include GitLab Flavored Markdown and some HTML tags. For example, you can format the emails to include a header and footer in accordance with your organization's brand guidelines. You can also include the following placeholders to display dynamic content specific to the Service Desk ticket or your GitLab instance.
| Placeholder | thank_you.md and new_participant | new_note.md | Description |
|---|---|---|---|
%{ISSUE_ID} | {{< yes >}} | {{< yes >}} | Ticket IID. |
%{ISSUE_PATH} | {{< yes >}} | {{< yes >}} | Project path appended with the ticket IID. |
%{ISSUE_URL} | {{< yes >}} | {{< yes >}} | URL of the ticket. External participants can only view the ticket if the project is public and ticket is not confidential (Service Desk tickets are confidential by default). |
%{ISSUE_DESCRIPTION} | {{< yes >}} | {{< yes >}} | Ticket description. If a user has edited the description, it may contain sensitive information that is not intended to be delivered to external participants. Use this placeholder with care and ideally only if you never modify ticket descriptions or your team is aware of the template design. |
%{UNSUBSCRIBE_URL} | {{< yes >}} | {{< yes >}} | Unsubscribe URL. Learn how to unsubscribe as an external participant and use unsubscribe headers in notification emails from GitLab. |
%{NOTE_TEXT} | {{< no >}} | {{< yes >}} | The new comment added to the ticket by a user. Take care to include this placeholder in new_note.md. Otherwise, the external participants may never see the updates on their Service Desk ticket. |
When a requester submits an issue through Service Desk, GitLab sends a thank you email. Without additional configuration, GitLab sends the default thank you email.
To create a custom thank you email template:
.gitlab/service_desk_templates/ directory of your repository, create a file named thank_you.md.{{< history >}}
new_participant email introduced in GitLab 17.0.{{< /history >}}
When an external participant is added to the ticket, GitLab sends a new participant email to let them know they are part of the conversation. Without additional configuration, GitLab sends the default new participant email.
To create a custom new participant email template:
.gitlab/service_desk_templates/ directory of your repository, create a file named new_participant.md.When a Service Desk ticket has a new public comment, GitLab sends a new note email. Without additional configuration, GitLab sends the content of the comment.
To keep your emails on brand, you can create a custom new note email template. To do so:
.gitlab/service_desk_templates/ directory in your repository, create a file named new_note.md.%{NOTE_TEXT} in the template to make sure the email recipient can
read the contents of the comment.{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Instance administrators can add a header, footer or additional text to the GitLab instance and apply
them to all emails sent from GitLab. If you're using a custom thank_you.md, new_participant.md or new_note.md, to include
this content, add %{SYSTEM_HEADER}, %{SYSTEM_FOOTER}, or %{ADDITIONAL_TEXT} to your templates.
For more information, see system header and footer messages and custom additional text.
You can select one description template per project to be appended to every new Service Desk ticket description.
You can set description templates at various levels:
The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups.
Prerequisites:
To use a custom description template with Service Desk:
Behind the scenes, Service Desk works by the special Support Bot user creating tickets. This user isn't a billable user, so it does not count toward the license limit count.
In GitLab 16.0 and earlier, comments generated from Service Desk emails show GitLab Support Bot
as the author. In GitLab 16.1 and later,
these comments show the email of the user who sent the email.
This feature only applies to comments made in GitLab 16.1 and later.
You can change the display name of the Support Bot user. Emails sent from Service Desk tickets have
this name in the From header. The default display name is GitLab Support Bot.
To edit the custom email display name:
{{< history >}}
{{< /history >}}
New tickets are confidential by default, so only project members with the Planner, Reporter, Developer, Maintainer, or Owner role can view them.
In private and internal projects, you can configure GitLab so that new tickets are not confidential by default, and any project member can view them.
In public projects, this setting is not available because new tickets are always confidential by default.
Prerequisites:
To disable this setting:
{{< history >}}
{{< /history >}}
You can configure GitLab to reopen closed tickets when an external participant adds a new comment on a ticket by email. This also adds an internal comment that mentions the assignees of the ticket and creates to-do items for them.
<i class="fa-youtube-play" aria-hidden="true"></i> For a walkthrough, see a short showcase video.
<!-- Video published on 2023-12-12 -->Prerequisites:
To enable this setting:
{{< details >}}
{{< /details >}}
{{< history >}}
service_desk_custom_email. Disabled by default.service_desk_custom_email removed in GitLab 16.7.{{< /history >}}
Configure a custom email address to show as the sender of your support communication. Maintain brand identity and instill confidence among support requesters with a domain they recognize.
<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see a short showcase video.
<!-- Video published on 2023-09-12 -->This feature is in beta. A beta feature is not production-ready, but is unlikely to change drastically before it's released. We encourage users to try beta features and provide feedback in the feedback issue.
You can use one custom email address for Service Desk per project and it must be unique across the instance.
The custom email address you want to use must meet all of the following requirements:
You can set up email forwarding.
Forwarded emails preserve the original From header.
Your service provider must support sub-addressing. An email address consists of a local part (everything before @) and a
domain part.
With email sub-addressing you can create unique variations of an email address by adding a + symbol followed
by any text to the local part. Given the email address [email protected], check whether sub-addressing is supported by
sending an email to [email protected]. This email should appear in your mailbox.
You have SMTP credentials (ideally, you should use an app password). The username and password are stored in the database using the Advanced Encryption Standard (AES) with a 256-bit key.
The SMTP host must be resolvable from the network of your GitLab instance (on GitLab Self-Managed) or the public internet (on GitLab.com).
You must have the Maintainer or Owner role for the project.
Service Desk must be configured for the project.
Configure and verify a custom email address when you want to send Service Desk emails using your own email address.
[!warning] When you set up email forwarding, use the address in the Service Desk email address to forward emails to field in the custom email form (the
incoming+...address). Do not forward to the alias address (contact-project+...) at the top of the Service Desk settings page. Forwarding to the alias address causesIncorrect forwarding targetverification failures.
incoming+... address that you must use as the forwarding target.The configuration has been saved and the verification of the custom email address is triggered.
+verify sub-addressing part).From header is preserved after forwarding.Typically the process takes only a few minutes.
To cancel verification at any time or if it fails, select Reset custom email. The settings page updates accordingly and reflects the current state of the verification. The SMTP credentials are deleted and you can start the configuration again.
On failure and success all project owners and the user who triggered the verification process receive a notification email with the verification result. If the verification failed, the email also contains details of the reason.
If the verification was successful, the custom email address is ready to be used. You can now enable sending Service Desk emails with the custom email address.
When configuring a custom email you might encounter the following issues.
You might get an error that states:
The given credentials (username and password) were rejected by the SMTP server,
or you need to explicitly set an authentication method.
This issue occurs when the SMTP server rejects the authentication credentials.
To resolve this issue:
Verify your username and password are correct.
If GitLab cannot automatically select a supported authentication method, do one of the following:
Test the available authentication methods: Plain, Login, and CRAM-MD5.
Check which authentication methods your SMTP server supports by running this command on the GitLab server:
swaks --to [email protected] \
--from [email protected] \
--auth-user [email protected] \
--server [email protected]:587 \
-tls-optional \
--auth-password your-app-password
In the output, find the line that starts with 250-AUTH,
then select one of the supported authentication methods in the custom email setup form.
If you're using Microsoft 365 and the error persists, disable conditional access and repeat the previous steps.
You might get an error that states that an incorrect forwarding target was used.
This occurs when the verification email was forwarded to a different email address than the project-specific Service Desk address that's displayed in the custom email configuration form.
You must use the Service Desk address generated from incoming_email. Forwarding to the additional
Service Desk alias address generated from service_desk_email is not supported because it doesn't support
all reply by email functionalities.
To troubleshoot this:
After the custom email address has been verified, administrators can enable or disable sending Service Desk emails with the custom email address.
To enable the custom email address:
To disable the custom email address:
In the top bar, select Search or go to and find your project.
Select Settings > General.
Expand Service Desk.
Turn off the Enable custom email toggle. Because you set up email forwarding, emails to your custom email address continue to be processed and appear as Service Desk Tickets in your project.
Service Desk emails to external participants are now sent using the GitLab instance's default outgoing email configuration.
To change the custom email configuration you must reset and remove it and configure custom email again.
To reset the configuration at any step in the process, select Reset custom email. The credentials are then removed from the database.
External participants can reply by email to Service Desk tickets. GitLab uses an email reply address with a 32-character reply key that corresponds to the ticket. When a custom email is configured, GitLab generates the reply address from that email.
Set up a custom email address for Service Desk when using Google Workspace with your own domain.
Prerequisites:
To configure a custom Service Desk email address with Google Workspace:
First, you must create and configure a Google Workspace account.
In Google Workspace:
[email protected]).Next, you must configure email forwarding in Google Workspace.
The following steps require moving between GitLab and Google Workspace.
In GitLab:
In Google Workspace:
In GitLab:
In Google Workspace:
Next, configure custom email address using a Google Workspace account to use with Service Desk.
In GitLab:
smtp.gmail.com.587.{{< history >}}
{{< /history >}}
Set up a custom email address for Service Desk when using Microsoft 365 (Exchange) with your own domain.
Prerequisites:
To configure a custom Service Desk email address with Microsoft 365:
First, you must create and configure a Microsoft 365 account. In this guide, use a licensed user for the custom email mailbox. You can also experiment with other configuration options.
In Microsoft 365 admin center:
[email protected]).
Use Azure Cloud Shell to allow SMTP client authentication:
Set-TransportConfig -SmtpClientAuthenticationDisabled $false
Use Azure Cloud Shell to allow legacy TLS clients using SMTP AUTH:
Set-TransportConfig -AllowLegacyTLSClients $true
If you want to forward to an external recipient, see this guide on how to enable external email forwarding. You might also want to create an outbound anti-spam policy to allow forwarding to external recipients only for users who need it.
Select Add sign-in method and select App password from the dropdown list.
Set a descriptive name for the app password, such as GitLab SD.
Select Next.
Copy the displayed password and store it in a secure place.
Optional. Ensure you can send emails using SMTP using the swaks command line tool.
Run the following command with your credentials and use the app password as the auth-password:
swaks --to [email protected] \
--from [email protected] \
--auth-user [email protected] \
--server smtp.office365.com:587 \
-tls-optional \
--auth-password <your_app_password>
Next, you must configure email forwarding in Microsoft 365.
The following steps require moving between GitLab and Microsoft 365 admin center.
In GitLab:
In the top bar, select Search or go to and find your project.
Select Settings > General
Expand Service Desk.
Note the email address below Service Desk email address to forward emails to without the sub-address part.
Emails aren't forwarded if the recipient address contains a sub-address (for example reply addresses generated by GitLab) and the forwarding email address contains a sub-address (the Service Desk email address to forward emails to).
For example, [email protected] becomes [email protected].
That's okay because Exchange online preserves the custom email address in the To header
after forwarding and GitLab can assign the correct project based on the custom email address.
In Microsoft 365 admin center:
<!-- vale gitlab_base.SubstitutionWarning = NO -->Next, configure a custom email address using a Microsoft 365 account to use with Service Desk.
In GitLab:
smtp.office365.com.587.{{< details >}}
{{< /details >}}
You can use an additional alias email address for Service Desk for an instance.
To do this, you must configure
a service_desk_email in the instance configuration. You can also configure a
custom suffix that replaces the default -issue- portion on the sub-addressing part.
[!note] On GitLab.com a custom mailbox is already configured with
contact-project+%{key}@incoming.gitlab.comas the email address. You can still configure the custom suffix in project settings.
Service Desk uses the incoming email
configuration by default. However, to have a separate email address for Service Desk,
configure service_desk_email with a custom suffix
in project settings.
Prerequisites:
address must include the +%{key} placeholder in the user portion of the address,
before the @. The placeholder is used to identify the project where the issue should be created.service_desk_email and incoming_email configurations must always use separate mailboxes
to make sure Service Desk emails are processed correctly.To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full:
{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
[!note] In GitLab 15.3 and later, Service Desk uses
webhook(internal API call) by default instead of enqueuing a Sidekiq job. To usewebhookon a Linux package installation running GitLab 15.3, you must generate a secret file. For more information, see merge request 5927. In GitLab 15.4, reconfiguring a Linux package installation generates this secret file automatically, so no secret file configuration setting is needed. For more information, see issue 1462.
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com"
gitlab_rails['service_desk_email_email'] = "[email protected]"
gitlab_rails['service_desk_email_password'] = "[REDACTED]"
gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
gitlab_rails['service_desk_email_idle_timeout'] = 60
gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
gitlab_rails['service_desk_email_host'] = "imap.gmail.com"
gitlab_rails['service_desk_email_port'] = 993
gitlab_rails['service_desk_email_ssl'] = true
gitlab_rails['service_desk_email_start_tls'] = false
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
service_desk_email:
enabled: true
address: "project_contact+%{key}@example.com"
user: "[email protected]"
password: "[REDACTED]"
host: "imap.gmail.com"
delivery_method: webhook
secret_file: .gitlab-mailroom-secret
port: 993
ssl: true
start_tls: false
log_path: "log/mailroom.log"
mailbox: "inbox"
idle_timeout: 60
expunge_deleted: true
{{< /tab >}}
{{< /tabs >}}
The configuration options are the same as for configuring incoming email.
{{< history >}}
{{< /history >}}
Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally use an encrypted file for the incoming email credentials.
Prerequisites:
The supported configuration items for the encrypted file are:
userpassword{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
If initially your Service Desk configuration in /etc/gitlab/gitlab.rb looked like:
gitlab_rails['service_desk_email_email'] = "[email protected]"
gitlab_rails['service_desk_email_password'] = "examplepassword"
Edit the encrypted secret:
sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim
Enter the unencrypted contents of the Service Desk email secret:
user: '[email protected]'
password: 'examplepassword'
Edit /etc/gitlab/gitlab.rb and remove the service_desk settings for email and password.
Save the file and reconfigure GitLab:
sudo gitlab-ctl reconfigure
{{< /tab >}}
{{< tab title="Helm chart (Kubernetes)" >}}
Use a Kubernetes secret to store the Service Desk email password. For more information, see Helm IMAP secrets.
{{< /tab >}}
{{< tab title="Docker" >}}
If initially your Service Desk 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['service_desk_email_email'] = "[email protected]"
gitlab_rails['service_desk_email_password'] = "examplepassword"
Get inside the container, and edit the encrypted secret:
sudo docker exec -t <container_name> bash
gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor
Enter the unencrypted contents of the Service Desk secret:
user: '[email protected]'
password: 'examplepassword'
Edit docker-compose.yml and remove the service_desk settings for email and password.
Save the file and restart GitLab:
docker compose up -d
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
If initially your Service Desk configuration in /home/git/gitlab/config/gitlab.yml looked like:
production:
service_desk_email:
user: '[email protected]'
password: 'examplepassword'
Edit the encrypted secret:
bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
Enter the unencrypted contents of the Service Desk secret:
user: '[email protected]'
password: 'examplepassword'
Edit /home/git/gitlab/config/gitlab.yml and remove the service_desk_email: settings for user and password.
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
{{< /tab >}}
{{< /tabs >}}
{{< history >}}
{{< /history >}}
service_desk_email can be configured to read Microsoft Exchange Online mailboxes with the Microsoft
Graph API instead of IMAP. Set up an OAuth 2.0 application for Microsoft Graph
the same way as for incoming email.
{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Edit /etc/gitlab/gitlab.rb and add the following lines, substituting
the values you want:
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
gitlab_rails['service_desk_email_email'] = "[email protected]"
gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph'
gitlab_rails['service_desk_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. For example:
gitlab_rails['service_desk_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
}
{{< /tab >}}
{{< tab title="Helm chart (Kubernetes)" >}}
Create the Kubernetes Secret containing the OAuth 2.0 application client secret:
kubectl create secret generic service-desk-email-client-secret --from-literal=secret=<YOUR-CLIENT_SECRET>
Create the Kubernetes Secret for the GitLab Service Desk email auth token.
Replace <name> with the name of the Helm release name for the GitLab installation:
kubectl create secret generic <name>-service-desk-email-auth-token --from-literal=authToken=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)
Export the Helm values:
helm get values gitlab > gitlab_values.yaml
Edit gitlab_values.yaml:
global:
appConfig:
serviceDeskEmail:
enabled: true
address: "project_contact+%{key}@example.onmicrosoft.com"
user: "[email protected]"
mailbox: inbox
inboxMethod: microsoft_graph
azureAdEndpoint: https://login.microsoftonline.com
graphEndpoint: https://graph.microsoft.com
tenantId: "YOUR-TENANT-ID"
clientId: "YOUR-CLIENT-ID"
clientSecret:
secret: service-desk-email-client-secret
key: secret
deliveryMethod: webhook
authToken:
secret: <name>-service-desk-email-auth-token
key: authToken
For Microsoft Cloud for US Government or other Azure deployments,
configure the azureAdEndpoint and graphEndpoint settings. These fields are case-sensitive:
global:
appConfig:
serviceDeskEmail:
[..]
azureAdEndpoint: https://login.microsoftonline.us
graphEndpoint: https://graph.microsoft.us
[..]
Save the file and apply the new values:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
{{< /tab >}}
{{< tab title="Docker" >}}
Edit docker-compose.yml:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
gitlab_rails['service_desk_email_email'] = "[email protected]"
gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph'
gitlab_rails['service_desk_email_inbox_options'] = {
'tenant_id': '<YOUR-TENANT-ID>',
'client_id': '<YOUR-CLIENT-ID>',
'client_secret': '<YOUR-CLIENT-SECRET>',
'poll_interval': 60 # Optional
}
Save the file and restart GitLab:
docker compose up -d
For Microsoft Cloud for US Government or other Azure deployments,
configure the azure_ad_endpoint and graph_endpoint settings:
Edit docker-compose.yml:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.onmicrosoft.com"
gitlab_rails['service_desk_email_email'] = "[email protected]"
gitlab_rails['service_desk_email_mailbox_name'] = "inbox"
gitlab_rails['service_desk_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
gitlab_rails['service_desk_email_inbox_method'] = 'microsoft_graph'
gitlab_rails['service_desk_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
}
Save the file and restart GitLab:
docker compose up -d
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Edit /home/git/gitlab/config/gitlab.yml:
service_desk_email:
enabled: true
address: "project_contact+%{key}@example.onmicrosoft.com"
user: "[email protected]"
mailbox: "inbox"
delivery_method: webhook
log_path: "log/mailroom.log"
secret_file: .gitlab-mailroom-secret
inbox_method: "microsoft_graph"
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. For example:
service_desk_email:
enabled: true
address: "project_contact+%{key}@example.onmicrosoft.com"
user: "[email protected]"
mailbox: "inbox"
delivery_method: webhook
log_path: "log/mailroom.log"
secret_file: .gitlab-mailroom-secret
inbox_method: "microsoft_graph"
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
{{< /tab >}}
{{< /tabs >}}
You can set a custom suffix in your project's Service Desk settings.
A suffix can contain only lowercase letters (a-z), numbers (0-9), or underscores (_).
When configured, the custom suffix creates a new Service Desk email address, consisting of the
service_desk_email_address setting and a key of the format: <project_full_path>-<custom_suffix>
Prerequisites:
For example, suppose the mygroup/myproject project Service Desk settings has the following configured:
support.contact+%{key}@example.com.The Service Desk email address for this project is: [email protected].
The incoming email address still works.
If you don't configure a custom suffix, the default project identification is used for identifying the project.
A multi-node environment is a setup where GitLab is run across multiple servers for scalability, fault tolerance, and performance reasons.
GitLab uses a separate process called mail_room to ingest new unread emails
from the incoming_email and service_desk_email mailboxes.
The GitLab Helm chart is made up of multiple subcharts, and one of them is
the Mailroom subchart. Configure the
common settings for incoming_email
and the common settings for service_desk_email.
In multi-node Linux package installation environments, run mail_room only on one node. Run it either on a single
rails node (for example, application_role)
or completely separately.
Add basic configuration for incoming_email and service_desk_email on every node
to render email addresses in the web UI and in generated emails.
Find the incoming_email or service_desk_email section in /etc/gitlab/gitlab.rb:
{{< tabs >}}
{{< tab title="incoming_email" >}}
gitlab_rails['incoming_email_enabled'] = true
gitlab_rails['incoming_email_address'] = "incoming+%{key}@example.com"
{{< /tab >}}
{{< tab title="service_desk_email" >}}
gitlab_rails['service_desk_email_enabled'] = true
gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@example.com"
{{< /tab >}}
{{< /tabs >}}
GitLab offers two methods to transport emails from mail_room to the GitLab
application. You can configure the delivery_method for each email setting individually:
Recommended: webhook (default in GitLab 15.3 and later) sends the email payload with an API POST request to your GitLab
application. It uses a shared token to authenticate. If you choose this method,
make sure the mail_room process can access the API endpoint and distribute the shared
token across all application nodes.
{{< tabs >}}
{{< tab title="incoming_email" >}}
gitlab_rails['incoming_email_delivery_method'] = "webhook"
# The URL that mail_room can contact. You can also use an internal URL or IP,
# just make sure mail_room can access the GitLab API with that address.
# Do not end with "/".
gitlab_rails['incoming_email_gitlab_url'] = "https://gitlab.example.com"
# The shared secret file that should contain a random token. Make sure it's the same on every node.
gitlab_rails['incoming_email_secret_file'] = ".gitlab_mailroom_secret"
{{< /tab >}}
{{< tab title="service_desk_email" >}}
gitlab_rails['service_desk_email_delivery_method'] = "webhook"
# The URL that mail_room can contact. You can also use an internal URL or IP,
# just make sure mail_room can access the GitLab API with that address.
# Do not end with "/".
gitlab_rails['service_desk_email_gitlab_url'] = "https://gitlab.example.com"
# The shared secret file that should contain a random token. Make sure it's the same on every node.
gitlab_rails['service_desk_email_secret_file'] = ".gitlab_mailroom_secret"
{{< /tab >}}
{{< /tabs >}}
If you experience issues with the webhook setup, use sidekiq to deliver the email payload directly to GitLab Sidekiq using Redis.
{{< tabs >}}
{{< tab title="incoming_email" >}}
# It uses the Redis configuration to directly add Sidekiq jobs
gitlab_rails['incoming_email_delivery_method'] = "sidekiq"
{{< /tab >}}
{{< tab title="service_desk_email" >}}
# It uses the Redis configuration to directly add Sidekiq jobs
gitlab_rails['service_desk_email_delivery_method'] = "sidekiq"
{{< /tab >}}
{{< /tabs >}}
Disable mail_room on all nodes that should not run email ingestion. For example, in /etc/gitlab/gitlab.rb:
mailroom['enable'] = false
Reconfigure GitLab for the changes to take effect.
After setting up all nodes and disabling the mail_room process, enable mail_room on a single node.
This node polls the mailboxes for incoming_email and service_desk_email on a regular basis and
move new unread emails to GitLab.
Choose an existing node that additionally handles email ingestion.
Add full configuration and credentials
for incoming_email and service_desk_email.
Enable mail_room on this node. For example, in /etc/gitlab/gitlab.rb:
mailroom['enable'] = true
Reconfigure GitLab on this node for the changes to take effect.