gitlab-org--gitlab-foss/doc/user/project/integrations/mattermost_slash_commands.md

stage	group	info
Create	Ecosystem	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 slash commands (FREE)

If your team uses Mattermost 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.

GitLab can also send events (such as issue created) to Mattermost as part of the separately configured Mattermost Notifications Service.

Prerequisites

Mattermost 3.4 or later is required. GitLab provides different methods of configuring Mattermost slash commands, depending on your configuration:

• Omnibus GitLab installations: Mattermost is bundled with Omnibus GitLab. To configure Mattermost for Omnibus GitLab, read the Omnibus GitLab Mattermost documentation.
• If Mattermost is installed on the same server as GitLab, use the automated configuration.
• For all other installations, use the manual configuration.

Automated configuration

If Mattermost is installed on the same server as GitLab, the configuration process can be done for you by GitLab.

Go to the Mattermost Slash Command service on your project and click Add to Mattermost button.

Manual configuration

To manually configure slash commands in Mattermost, you must:

1. Enable custom slash commands in Mattermost.
2. Get configuration values from GitLab.
3. Create a new slash command in Mattermost.
4. 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.

To enable custom slash commands from the Mattermost administrator console:

1. Sign in to Mattermost as a user with administrator privileges.
2. Next to your username, click the {ellipsis_v} Settings icon, and select System Console.
3. Select Integration Management, and set these values to TRUE:
   • Enable Custom Slash Commands
   • Enable integrations to override usernames
   • Enable integrations to override profile picture icons
4. Click Save, but do not close this browser tab, because 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:

1. In a different browser tab than your current Mattermost session, sign in to GitLab as a user with Administrator role.
2. On the top bar, select Menu > {admin} Admin.
3. In the left menu, select Settings > Integrations, then select Mattermost slash commands.
4. GitLab displays potential values for Mattermost settings. Copy the Request URL as you need it for the next step. All other values are suggestions.
5. 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.

Create a slash command

To create a slash command, you need the values you obtained from GitLab in the previous step:

1. In the Mattermost tab you left open when you enabled custom slash commands, go to your team page.

2. Click the {ellipsis_v} Settings icon, and select Integrations.

3. In the left menu, select Slash commands.

4. Click Add Slash Command:

   

5. Provide a Display Name and Description for your new command.

6. Provide a Command Trigger Word according to your application's configuration:

   • 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 to your project, such as /project-name or /gitlab-project-name.

7. For Request URL, provide the value you copied from GitLab when you viewed configuration values.

8. For all other values, you may use the suggestions from GitLab or use your preferred values.

9. Copy the Token value, as you need it in a later step, and click Done.

Provide the Mattermost token to GitLab

When you create a new slash command in Mattermost, it generates a token you must provide to GitLab:

1. In the GitLab browser tab from getting configuration values from GitLab, select the Active check box to enable this configuration.

2. In the Token field, paste the token you obtained from Mattermost. ensure that the Active toggle is enabled.

   

3. Click Save changes for the changes to take effect.

Your slash command can now communicate with your GitLab project.

Authorizing Mattermost to interact with GitLab

The first time a user interacts with the newly created slash commands, Mattermost triggers an authorization process.

This connects your Mattermost user with your GitLab user. You can see all authorized chat accounts in your profile's page under Chat.

When the authorization process is complete, you can start interacting with GitLab using the Mattermost commands.

Available slash commands

The available slash commands for Mattermost are:

Command	Description	Example
/<trigger> issue new <title> ⇧ Shift+↵ Enter <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 job that deploys from one environment to another, for example staging to production. CI/CD must be properly configured.	/gitlab deploy staging to production

To see a list of available commands to interact with GitLab, type the trigger word followed by help. Example: /gitlab help

Permissions

The permissions to run the available commands derive from the permissions you have on the project.

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

• Mattermost slash commands documentation
• Omnibus GitLab Mattermost