2020-10-24 23:57:45 +05:30
---
stage: Create
group: Ecosystem
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-24 23:57:45 +05:30
---
2021-04-29 21:17:54 +05:30
# Mattermost notifications service **(FREE)**
2017-08-17 22:00:37 +05:30
2021-04-29 21:17:54 +05:30
Use the Mattermost notifications service to send notifications for GitLab events
(for example, `issue created` ) to Mattermost. You must configure both [Mattermost ](#configure-mattermost-to-receive-gitlab-notifications )
and [GitLab ](#configure-gitlab-to-send-notifications-to-mattermost ).
2019-09-30 21:07:59 +05:30
2021-04-29 21:17:54 +05:30
You can also use [Mattermost slash commands ](mattermost_slash_commands.md ) to control
GitLab inside Mattermost.
2019-09-30 21:07:59 +05:30
2021-04-29 21:17:54 +05:30
## Configure Mattermost to receive GitLab notifications
2017-08-17 22:00:37 +05:30
2021-04-29 21:17:54 +05:30
To use the Mattermost integration you must create an incoming webhook integration
in Mattermost:
2017-08-17 22:00:37 +05:30
2019-02-15 15:39:39 +05:30
1. Sign in to your Mattermost instance.
2021-04-29 21:17:54 +05:30
1. [Enable incoming webhooks ](https://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks ).
1. [Add an incoming webhook ](https://docs.mattermost.com/developer/webhooks-incoming.html#creating-integrations-using-incoming-webhooks ).
2019-02-15 15:39:39 +05:30
1. Choose a display name, description and channel, those can be overridden on GitLab.
2021-02-22 17:27:13 +05:30
1. Save it and copy the **Webhook URL** because we need this later for GitLab.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost administrator
2019-12-04 20:38:33 +05:30
to enable it on:
- **Mattermost System Console > Integrations > Integration Management** in Mattermost
versions 5.12 and later.
- **Mattermost System Console > Integrations > Custom Integrations** in Mattermost
versions 5.11 and earlier.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
Display name override is not enabled by default, you need to ask your administrator to enable it on that same section.
2017-08-17 22:00:37 +05:30
2021-04-29 21:17:54 +05:30
## Configure GitLab to send notifications to Mattermost
2017-08-17 22:00:37 +05:30
2021-04-29 21:17:54 +05:30
After the Mattermost instance has an incoming webhook set up, you can set up GitLab
to send the notifications.
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
Navigate to the [Integrations page ](overview.md#accessing-integrations )
2021-04-29 21:17:54 +05:30
and select the **Mattermost notifications** service. Select the GitLab events
you want to generate notifications for.
2017-08-17 22:00:37 +05:30
2021-04-29 21:17:54 +05:30
For each event you select, input the Mattermost channel you want to receive the
notification. You do not need to add the hash sign (`#`).
2017-08-17 22:00:37 +05:30
2021-04-29 21:17:54 +05:30
Then fill in the integration configuration:
2017-08-17 22:00:37 +05:30
| Field | Description |
| ----- | ----------- |
2021-04-29 21:17:54 +05:30
| **Webhook** | The incoming webhook URL on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` . |
| **Username** | (Optional) The username to show on messages sent to Mattermost. Fill this in to change the username of the bot. |
| **Notify only broken pipelines** | If you enable the **Pipeline** event and you want to be notified about failed pipelines only. |
| **Branches to be notified** | Select which branches to send notifications for. |
| **Labels to be notified** | (Optional) Labels that the issue or merge request must have to trigger a notification. Leave blank to get notifications for all issues and merge requests. |
