Mattermost slash commands

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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.

For a list of available slash commands, see Slash commands.

Configuration options

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

Configure automatically

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

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Integrations.
  3. Select Mattermost slash commands.
  4. Under 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 self-compiled installations.
  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 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 left sidebar, at the bottom, select Admin.
  3. 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 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

Prerequisites:

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.

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.