Service Desk (CORE)

Introduced in GitLab Premium 9.1.

Moved to GitLab Starter in 13.0.

Moved to GitLab Core in 13.2.

Service Desk is a module that allows your team to connect with any external party through email, without any external tools. An ongoing conversation in the same place as where your software is built ensures user feedback ends up where it's needed.

With Service Desk, you can provide efficient email support to your customers. They can email you bug reports, feature requests, or general feedback. They all end up in your GitLab project as new issues. In turn, your team can respond directly from the project.

As Service Desk is built right into GitLab itself, the complexity and inefficiencies of multiple tools and external integrations are eliminated. This significantly shortens the cycle time from feedback to software update.

For an overview, check the video demonstration on GitLab Service Desk.

How it works

GitLab Service Desk enables people to create issues in your GitLab instance without needing their own user account.

It provides a unique email address for end users to create issues in a project. Follow-up notes can be sent either through the GitLab interface or by email. End users only see the thread through email.

For instance, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed with GitLab CI/CD.

Here's how Service Desk works for you:

You provide a project-specific email address to your paying customers, who can email you directly from the application.
Each email they send creates an issue in the appropriate project.
Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues.
Your team communicates back and forth with the customer to understand the request.
Your team starts working on implementing code to solve your customer's problem.
When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically.
The customer's requests are handled through email, without ever having access to your GitLab instance.
Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer.

Configuring Service Desk

NOTE: Service Desk is enabled on GitLab.com. You can skip step 1 below; you only need to enable it per project.

If you have project maintainer access you have the option to set up Service Desk. Follow these steps:

Set up incoming email for the GitLab instance. We recommend using email sub-addressing, but in GitLab 11.7 and later you can also use catch-all mailboxes.
Navigate to your project's Settings > General and locate the Service Desk section.
Enable the Activate Service Desk toggle. This reveals a unique email address to email issues to the project. These issues are confidential, so they are only visible to project members. Note that in GitLab 11.7, we updated the generated email address's format. The older format is still supported, however, allowing existing aliases or contacts to continue working.

WARNING: This email address can be used by anyone to create an issue on this project, regardless of their access level to your GitLab instance. We recommend putting this behind an alias so it can be changed if needed. We also recommend enabling Akismet on your GitLab instance to add spam checking to this service. Unblocked email spam would result in many spam issues being created.

If you have templates in your repository, you can optionally select one from the selector menu to append it to all Service Desk issues.

Service Desk is now enabled for this project! You should be able to access it from your project's Issues menu.

Using customized email templates

Introduced in GitLab Premium 12.7.

Moved to GitLab Starter in 13.0.

Moved to GitLab Core in 13.2.

An email is sent to the author when:

A user submits a new issue using Service Desk.
A new note is created on a Service Desk issue.

The body of these email messages can be customized by using templates. To create a new customized template, create a new Markdown (.md) file inside the .gitlab/service_desk_templates/ directory in your repository. Commit and push to your default branch.

Thank you email

The Thank you email is the email sent to a user after they submit an issue. The filename of the template has to be thank_you.md. There are a few placeholders you can use which are automatically replaced in the email:

%{ISSUE_ID}: issue IID
%{ISSUE_PATH}: project path appended with the issue IID

As the Service Desk issues are created as confidential (only project members can see them) the response email does not provide the issue link.

New note email

When a user-submitted issue receives a new comment, GitLab sends a New note email to the user. The filename of this template must be new_note.md, and you can use these placeholders in the email:

%{ISSUE_ID}: issue IID
%{ISSUE_PATH}: project path appended with the issue IID
%{NOTE_TEXT}: note text

Using custom email display name

Introduced in GitLab 12.8.

You can customize the email display name. Emails sent from Service Desk have this name in the From header. The default display name is GitLab Support Bot.

To edit the custom email display name:

In a project, go to Settings > General > Service Desk.
Enter a new name in Email display name.
Select Save Changes.

Using custom email address

Introduced in GitLab Premium 13.0.

Feature flag removed in GitLab 13.8.

If the service_desk_email is configured, then you can create Service Desk issues by sending emails to the Service Desk email address. The default address has the following format: project_contact+%{key}@example.com.

The %{key} part is used to find the project where the issue should be created. The %{key} part combines the path to the project and configurable project name suffix: <project_full_path>-<project_name_suffix>.

You can set the project name suffix in your project's Service Desk settings. It can contain only lowercase letters (a-z), numbers (0-9), or underscores (_).

NOTE: The service_desk_email and incoming_email configurations should always use separate mailboxes. This is important, because emails picked from service_desk_email mailbox are processed by a different worker and it would not recognize incoming_email emails.

To configure a custom email address for Service Desk, add the following snippets to your configuration file:

Example for installations from source:

service_desk_email:
  enabled: true
  address: "project_contact+%{key}@example.com"
  user: "project_support@example.com"
  password: "[REDACTED]"
  host: "imap.gmail.com"
  port: 993
  ssl: true
  start_tls: false
  log_path: "log/mailroom.log"
  mailbox: "inbox"
  idle_timeout: 60
  expunge_deleted: true

Example for Omnibus GitLab installations:

gitlab_rails['service_desk_email_enabled'] = true

gitlab_rails['service_desk_email_address'] = "project_contact+%{key}@gmail.com"

gitlab_rails['service_desk_email_email'] = "project_support@gmail.com"

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

In this case, suppose the mygroup/myproject project Service Desk settings has the project name suffix set to support, and a user sends an email to project_contact+mygroup-myproject-support@example.com. As a result, a new Service Desk issue is created from this email in the mygroup/myproject project.

The configuration options are the same as for configuring incoming email.

Using Service Desk

There are a few ways Service Desk can be used.

As an end user (issue creator)

To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and receive an email back confirming receipt:

This also gives the end user an option to unsubscribe.

If they don't choose to unsubscribe, then any new comments added to the issue are sent as emails:

Any responses they send via email are displayed in the issue itself.

As a responder to the issue

For responders to the issue, everything works just like other GitLab issues. GitLab displays a familiar-looking issue tracker where responders can see issues created through customer support requests, and filter or interact with them.

Messages from the end user are shown as coming from the special Support Bot user. You can read and write comments as you normally do in GitLab:

Note that:

The project's visibility (private, internal, public) does not affect Service Desk.
The path to the project, including its group or namespace, are shown in emails.

Support Bot user

Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user does not count toward the license limit count.