GitLab Mattermost

This document applies to GitLab 11.0 and later.

You can run a GitLab Mattermost service on your GitLab server. Mattermost is not part of the single application that GitLab is. There is a good integration between with GitLab, and our Omnibus installer allows you to easily install it. But it is a separate application from a separate company.


Each release of GitLab Mattermost is compiled and manually tested on an AMD 64 chipset for Linux. ARM chipsets and operating systems, like Raspberry Pi, are not supported.

Getting started

GitLab Mattermost expects to run on its own virtual host. In your DNS settings, you need two entries pointing to the same machine. For example, and

GitLab Mattermost is disabled by default. To enable it:

  1. Edit /etc/gitlab/gitlab.rb and add the Mattermost external URL:

    mattermost_external_url ''
  2. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure
  3. Confirm that GitLab Mattermost is reachable at and authorized to connect to GitLab. Authorizing Mattermost with GitLab allows users to use GitLab as an SSO provider.

The Omnibus GitLab package attempts to automatically authorize GitLab Mattermost with GitLab if the applications are running on the same server.

Automatic authorization requires access to the GitLab database. If the GitLab database is not available you need to manually authorize GitLab Mattermost for access to GitLab using the process described in the Authorize GitLab Mattermost section.

Configuring Mattermost

Starting in GitLab 11.0, Mattermost can be configured using the Mattermost System Console. An extensive list of Mattermost settings and where they can be set is available in the Mattermost documentation.

While using the System Console is recommended, you can also configure Mattermost using one of the following options:

  1. Edit the Mattermost configuration directly through /var/opt/gitlab/mattermost/config.json.
  2. Specify environment variables used to run Mattermost by changing the mattermost['env'] setting in gitlab.rb. Any settings configured in this way are disabled from the System Console and cannot be changed without restarting Mattermost.

Running GitLab Mattermost with HTTPS

Place the SSL certificate and SSL certificate key inside /etc/gitlab/ssl. If the directory doesn’t exist, create it:

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp mattermost.gitlab.example.key mattermost.gitlab.example.crt /etc/gitlab/ssl/

In /etc/gitlab/gitlab.rb specify the following configuration:

mattermost_external_url 'https://mattermost.gitlab.example'
mattermost_nginx['redirect_http_to_https'] = true

If you haven’t named your certificate and key mattermost.gitlab.example.crt and mattermost.gitlab.example.key then you need to also add the full paths as shown below.

mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt"
mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key"

where mattermost-nginx.crt and mattermost-nginx.key are SSL cert and key, respectively.

Once the configuration is set, run sudo gitlab-ctl reconfigure to apply the changes.

Running GitLab Mattermost on its own server

If you want to run GitLab and GitLab Mattermost on two separate servers the GitLab services are still set up on your GitLab Mattermost server, but they do not accept user requests or consume system resources. You can use the following settings and configuration details on the GitLab Mattermost server to effectively disable the GitLab service bundled into the Omnibus package.

mattermost_external_url ''

# Shut down GitLab services on the Mattermost server
gitlab_rails['enable'] = false
redis['enable'] = false
postgres_exporter['enable'] = false
grafana['enable'] = false

Then follow the appropriate steps in the Authorize GitLab Mattermost section. Last, to enable integrations with GitLab add the following on the GitLab Server:

gitlab_rails['mattermost_host'] = ""

By default GitLab Mattermost requires all users to sign up with GitLab and disables the sign-up by email option. See Mattermost documentation on GitLab SSO.

Manually (re)authorizing GitLab Mattermost with GitLab

Reauthorize GitLab Mattermost

To reauthorize GitLab Mattermost, you first need to revoke the existing authorization. This can be done in the Settings > Applications area of GitLab. Then follow the steps below to complete authorization.

Authorize GitLab Mattermost

Navigate to the Settings > Applications area in GitLab. Create a new application and for the Redirect URI use the following (replace http with https if you use HTTPS):

Note that you do not need to select any options under Scopes. Choose Save application.

Once the application is created you are provided with an Application ID and Secret. One other piece of information needed is the URL of GitLab instance. Return to the server running GitLab Mattermost and edit the /etc/gitlab/gitlab.rb configuration file as follows using the values you received above:

mattermost['gitlab_enable'] = true
mattermost['gitlab_id'] = "12345656"
mattermost['gitlab_secret'] = "123456789"
mattermost['gitlab_scope'] = ""
mattermost['gitlab_auth_endpoint'] = ""
mattermost['gitlab_token_endpoint'] = ""
mattermost['gitlab_user_api_endpoint'] = ""

Save the changes and then run sudo gitlab-ctl reconfigure. If there are no errors your GitLab and GitLab Mattermost should be configured correctly.

Specify numeric user and group identifiers

Omnibus GitLab creates a user and group mattermost. You can specify the numeric identifiers for these users in /etc/gitlab/gitlab.rb as follows:

mattermost['uid'] = 1234
mattermost['gid'] = 1234

Run sudo gitlab-ctl reconfigure to apply the changes.

Setting custom environment variables

If necessary you can set custom environment variables to be used by Mattermost via /etc/gitlab/gitlab.rb. This can be useful if the Mattermost server is operated behind a corporate internet proxy. In /etc/gitlab/gitlab.rb supply a mattermost['env'] with a hash value. For example:

mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "NO_PROXY" => "my_no_proxy"}

Run sudo gitlab-ctl reconfigure to apply the changes.

Connecting to the bundled PostgreSQL database

If you need to connect to the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can connect as the PostgreSQL superuser:

sudo gitlab-psql -d mattermost_production

Back up GitLab Mattermost

GitLab Mattermost is not included in the regular Omnibus GitLab backup Rake task.

The general Mattermost backup and disaster recovery documentation can be used as a guide on what needs to be backed up.

Back up the bundled PostgreSQL database

If you need to back up the bundled PostgreSQL database and are using the default Omnibus GitLab database configuration, you can back up using this command:

sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz

Back up the data directory and config.json

Mattermost has a data directory and config.json file that need to be backed up as well:

sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json

Restore GitLab Mattermost

If you have previously created a backup of GitLab Mattermost, you can run the following commands to restore it:

# Stop Mattermost so we don't have any open database connections
sudo gitlab-ctl stop mattermost

# Drop the Mattermost database
sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Create the Mattermost database
sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Perform the database restore
# Replace /tmp/mattermost_dbdump_2021-08-05.sql.gz with your backup
sudo -u mattermost sh -c "zcat /tmp/mattermost_dbdump_2021-08-05.sql.gz | /opt/gitlab/embedded/bin/psql -U gitlab_mattermost -h /var/opt/gitlab/postgresql -p 5432 mattermost_production"

# Restore the data directory and config.json
# Replace /tmp/mattermost_data_2021-08-09.gz with your backup
sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost

# Fix permissions if required
sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data
sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json

# Start Mattermost
sudo gitlab-ctl start mattermost