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

stage	group	info
Ecosystem	Integrations	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)

You can use slash commands to run common GitLab operations, like creating an issue, from a Mattermost chat environment.

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

Configuration options

GitLab provides different ways to configure Mattermost slash commands. For any of these options, you must have Mattermost 3.4 or later.

• 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.

Configure automatically

If Mattermost is installed on the same server as GitLab, you can automatically configure Mattermost slash commands:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > Integrations.
3. In Add an integration, select Mattermost slash commands.
4. In Enable integration, ensure the Active checkbox is selected.
5. Select Add to Mattermost, and select Save changes.

Configure manually

To manually configure slash commands in Mattermost, you must:

1. Enable custom slash commands in Mattermost. (This step is required only for installations from source.)
2. Get configuration values from GitLab.
3. Create a slash command in Mattermost.
4. Provide the Mattermost token to GitLab.

Enable custom slash commands in Mattermost

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, select 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. Select Save, but do not close this browser tab. You need it in a later step.

Get configuration values from GitLab

To get configuration values from GitLab:

1. In a different browser tab, sign in to GitLab as a user with administrator access.
2. On the top bar, select Menu > Admin.
3. On the left sidebar, select Settings > Integrations.
4. Select Mattermost slash commands. GitLab displays potential values for Mattermost settings.
5. Copy the Request URL value. All other values are suggestions.
6. Do not close this browser tab. You need it in a later step.

Create a slash command in Mattermost

To create a slash command in Mattermost:

1. In the Mattermost browser tab, go to your team page.

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

3. On the left sidebar, select Slash commands.

4. Select Add Slash Command.

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

6. Provide a Command Trigger Word based on 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, paste the value you copied from GitLab.

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

9. Copy the Token value, and select Done.

Provide the Mattermost token to GitLab

Creating a slash command in Mattermost generates a token you must provide to GitLab:

1. In the GitLab browser tab, select the Active checkbox.
2. In the Token text box, paste the token you copied from Mattermost.
3. Select Save changes.

Your slash command can now communicate with your GitLab project.

Connect your GitLab account to Mattermost

Prerequisite:

• To run slash commands, you must have permission to perform the action in the GitLab project.

To interact with GitLab using Mattermost slash commands:

1. In a Mattermost chat environment, run your new slash command.
2. 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

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/CD job that deploys from one environment to another (for example, staging to production). CI/CD must be properly configured.	/gitlab deploy staging to production
/<trigger> help	View a list of available slash commands.	/gitlab help

Related topics

• Mattermost slash commands
• Omnibus GitLab Mattermost

Troubleshooting

When a Mattermost slash command does not trigger an event in GitLab:

• 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.