diff options
Diffstat (limited to 'doc/user/project/integrations/mattermost.md')
-rw-r--r-- | doc/user/project/integrations/mattermost.md | 55 |
1 files changed, 24 insertions, 31 deletions
diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 6a93fc0fb06..0a32119d572 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,18 +4,23 @@ group: Ecosystem 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 --- -# Mattermost Notifications Service **(FREE)** +# Mattermost notifications service **(FREE)** -The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. +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). -You can also use Mattermost slash commands to control GitLab inside Mattermost. This is the separately configured [Mattermost slash commands](mattermost_slash_commands.md). +You can also use [Mattermost slash commands](mattermost_slash_commands.md) to control +GitLab inside Mattermost. -## On Mattermost +## Configure Mattermost to receive GitLab notifications -To enable Mattermost integration you must create an incoming webhook integration: +To use the Mattermost integration you must create an incoming webhook integration +in Mattermost: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +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). 1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it and copy the **Webhook URL** because we need this later for GitLab. @@ -29,36 +34,24 @@ to enable it on: Display name override is not enabled by default, you need to ask your administrator to enable it on that same section. -## On GitLab +## Configure GitLab to send notifications to Mattermost -After you set up Mattermost, it's time to set up GitLab. +After the Mattermost instance has an incoming webhook set up, you can set up GitLab +to send the notifications. Navigate to the [Integrations page](overview.md#accessing-integrations) -and select the **Mattermost notifications** service to configure it. -There, you see a checkbox with the following events that can be triggered: +and select the **Mattermost notifications** service. Select the GitLab events +you want to generate notifications for. -- Push -- Issue -- Confidential issue -- Merge request -- Note -- Confidential note -- Tag push -- Pipeline -- Wiki page -- Deployment +For each event you select, input the Mattermost channel you want to receive the +notification. You do not need to add the hash sign (`#`). -Below each of these event checkboxes, you have an input field to enter -which Mattermost channel you want to send that event message. Enter your preferred channel handle (the hash sign `#` is optional). - -At the end, fill in your Mattermost details: +Then fill in the integration configuration: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | -| **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | -| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | -| **Branches to be notified** | Select which types of branches to send notifications for. | -| **Labels to be notified** | Optional labels that the issue or merge request must have in order to trigger a notification. Leave blank to get all notifications. | - -![Mattermost configuration](img/mattermost_configuration_v2.png) +| **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. | |