diff options
Diffstat (limited to 'doc/user/project/integrations/mattermost_slash_commands.md')
| -rw-r--r-- | doc/user/project/integrations/mattermost_slash_commands.md | 167 |
1 files changed, 72 insertions, 95 deletions
diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 768acb02ee6..28a5f2eec18 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -6,48 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Mattermost slash commands **(FREE)** -If your team uses [Mattermost](https://mattermost.com/) as a chat service, you can -integrate GitLab commands into Mattermost chat. This integration enables users to -run common operations, such as creating a GitLab issue, from the Mattermost chat -environment. +You can use slash commands to run common GitLab operations, like creating an issue, +from a [Mattermost](https://mattermost.com/) chat environment. GitLab can also send events (such as `issue created`) to Mattermost as part of the -separately configured [Mattermost Notifications Service](mattermost.md). +separately configured [Mattermost notifications](mattermost.md). -## Prerequisites +## Configuration options -Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/) is required. -GitLab provides different methods of configuring Mattermost slash commands, depending -on your configuration: +GitLab provides different ways to configure Mattermost slash commands. For any of these options, +you must have Mattermost [3.4 or later](https://mattermost.com/blog/category/platform/releases/). - **Omnibus GitLab installations**: Mattermost is bundled with - [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the - [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). + [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, + read the [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the - [automated configuration](#automated-configuration). -- **For all other installations**, use the [manual configuration](#manual-configuration). + [automated configuration](#configure-automatically). +- **For all other installations**, use the [manual configuration](#configure-manually). -## Automated configuration +## Configure automatically -If Mattermost is installed on the same server as GitLab, the configuration process can be -done for you by GitLab. +If Mattermost is installed on the same server as GitLab, +you can automatically configure Mattermost slash commands: -Go to the Mattermost Slash Command service on your project and select **Add to Mattermost**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. In **Add an integration**, select **Mattermost slash commands**. +1. In **Enable integration**, ensure the **Active** checkbox is selected. +1. Select **Add to Mattermost**, and select **Save changes**. -## Manual configuration +## Configure manually To manually configure slash commands in Mattermost, you must: -1. [Enable custom slash commands](#enable-custom-slash-commands) in Mattermost. -1. [Get configuration values](#get-configuration-values-from-gitlab) from GitLab. -1. [Create a new slash command](#create-a-slash-command) in Mattermost. -1. [Provide the Mattermost token](#provide-the-mattermost-token-to-gitlab) to GitLab. +1. [Enable custom slash commands in Mattermost](#enable-custom-slash-commands-in-mattermost). + (This step is required only for installations from source.) +1. [Get configuration values from GitLab](#get-configuration-values-from-gitlab). +1. [Create a slash command in Mattermost](#create-a-slash-command-in-mattermost). +1. [Provide the Mattermost token to GitLab](#provide-the-mattermost-token-to-gitlab). -### Enable custom slash commands - -NOTE: -Omnibus GitLab installations are preconfigured. This step is required only for -installations from source. +### Enable custom slash commands in Mattermost To enable custom slash commands from the Mattermost administrator console: @@ -58,80 +56,68 @@ To enable custom slash commands from the Mattermost administrator console: - **Enable Custom Slash Commands** - **Enable integrations to override usernames** - **Enable integrations to override profile picture icons** -1. Select **Save**, but do not close this browser tab, because you need it in +1. Select **Save**, but do not close this browser tab. You need it in a later step. ### Get configuration values from GitLab -After you enable custom slash commands in Mattermost, you need configuration -information from GitLab. To get this information: +To get configuration values from GitLab: -1. In a different browser tab than your current Mattermost session, sign in to +1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the top bar, select **Menu > Admin**. -1. In the left menu, select **Settings > Integrations**, then select - **Mattermost slash commands**. -1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** - as you need it for the next step. All other values are suggestions. -1. Do not close this browser tab, because you need it in future steps. - -Next, create a slash command in Mattermost with the values from GitLab. +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. +1. Copy the **Request URL** value. All other values are suggestions. +1. Do not close this browser tab. You need it in a later step. -### Create a slash command +### Create a slash command in Mattermost -To create a slash command, you need the values you obtained from GitLab in -the previous step: +To create a slash command in Mattermost: -1. In the Mattermost tab you left open when you - [enabled custom slash commands](#enable-custom-slash-commands), go to your - team page. +1. [In the Mattermost browser tab](#enable-custom-slash-commands-in-mattermost), + go to your team page. 1. Select the **{ellipsis_v}** **Settings** icon, and select **Integrations**. -1. In the left menu, select **Slash commands**. -1. Select **Add Slash Command**: - -  +1. On the left sidebar, select **Slash commands**. +1. Select **Add Slash Command**. 1. Provide a **Display Name** and **Description** for your new command. -1. Provide a **Command Trigger Word** according to your application's configuration: +1. Provide a **Command Trigger Word** based on your application's configuration: - - **If you intend to only connect one project to your Mattermost team**: Use + - **If you intend to only connect one project to your Mattermost team**, use `/gitlab` for your trigger word. - - **If you intend to connect multiple projects**: Use a trigger word that relates + - **If you intend to connect multiple projects**, use a trigger word that relates to your project, such as `/project-name` or `/gitlab-project-name`. -1. For **Request URL**, provide the value you copied from GitLab when you - [viewed configuration values](#get-configuration-values-from-gitlab). -1. For all other values, you may use the suggestions from GitLab or use your +1. For **Request URL**, [paste the value you copied from GitLab](#get-configuration-values-from-gitlab). +1. For all other values, you may use the suggestions from GitLab or your preferred values. -1. Copy the **Token** value, as you need it in a later step, and select **Done**. +1. Copy the **Token** value, and select **Done**. ### Provide the Mattermost token to GitLab -When you create a new slash command in Mattermost, it generates a token you must +Creating a slash command in Mattermost generates a token you must provide to GitLab: -1. In the GitLab browser tab from - [getting configuration values from GitLab](#get-configuration-values-from-gitlab), - select the **Active** checkbox to enable this configuration. -1. In the **Token** field, paste the token you obtained from Mattermost. - ensure that the **Active** toggle is enabled. - -  - -1. Select **Save changes** for the changes to take effect. +1. [In the GitLab browser tab](#get-configuration-values-from-gitlab), + select the **Active** checkbox. +1. In the **Token** text box, [paste the token you copied from Mattermost](#create-a-slash-command-in-mattermost). +1. Select **Save changes**. Your slash command can now communicate with your GitLab project. -## Authorizing Mattermost to interact with GitLab +## Connect your GitLab account to Mattermost -The first time a user interacts with the newly created slash commands, -Mattermost triggers an authorization process. +Prerequisite: - +- To run [slash commands](#available-slash-commands), you must have + [permission](../../permissions.md#project-members-permissions) to + perform the action in the GitLab project. -This connects your Mattermost user with your GitLab user. You can -see all authorized chat accounts in your profile's page under **Chat**. +To interact with GitLab using Mattermost slash commands: -When the authorization process is complete, you can start interacting with -GitLab using the Mattermost commands. +1. In a Mattermost chat environment, run your new slash command. +1. Select **connect your GitLab account** to authorize access. + +You can see all authorized chat accounts in your Mattermost profile page under **Chat**. ## Available slash commands @@ -139,30 +125,21 @@ The available slash commands for Mattermost are: | Command | Description | Example | | ------- | ----------- | ------- | -| <kbd>/<trigger> issue new <title> <kbd>⇧ Shift</kbd>+<kbd>↵ Enter</kbd> <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | -| <kbd>/<trigger> issue show <issue-number></kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | -| <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | - -To see a list of available commands to interact with GitLab, type the -trigger word followed by <kbd>help</kbd>. Example: `/gitlab help` - - +| `/<trigger> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | +| `/<trigger> issue show <issue-number>` | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | +| `/<trigger> deploy <environment> to <environment>` | Start the CI/CD job that deploys from one environment to another (for example, `staging` to `production`). CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | +| `/<trigger> help` | View a list of available slash commands. | `/gitlab help` | -## Permissions +## Related topics -The permissions to run the [available commands](#available-slash-commands) derive from -the [permissions you have on the project](../../permissions.md#project-members-permissions). +- [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) +- [Omnibus GitLab Mattermost](../../../integration/mattermost/index.md) ## Troubleshooting -If an event is not being triggered, confirm that the channel you're using is a public one. -Mattermost webhooks do not have access to private channels. - -If a private channel is required, you can edit the webhook's channel in Mattermost and -select a private channel. It is not possible to use different channels for -different types of notifications. All events are sent to the specified channel. - -## Further reading +When a Mattermost slash command does not trigger an event in GitLab: -- [Mattermost slash commands documentation](https://docs.mattermost.com/developer/slash-commands.html) -- [Omnibus GitLab Mattermost](../../../integration/mattermost/) +- Ensure you're using a public channel. + Mattermost webhooks do not have access to private channels. +- If you require a private channel, edit the webhook channel, + and select a private one. All events are sent to the specified channel. |