- Automated configuration
- Manual configuration
- Authorizing Mattermost to interact with GitLab
- Available slash commands
- Further reading
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.
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.
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 select Add to Mattermost.
To manually configure slash commands in Mattermost, you must:
- Enable custom slash commands in Mattermost.
- Get configuration values from GitLab.
- Create a new slash command in Mattermost.
- Provide the Mattermost token to GitLab.
To enable custom slash commands from the Mattermost administrator console:
- Sign in to Mattermost as a user with administrator privileges.
- Next to your username, select the Settings icon, and select System Console.
- Select Integration Management, and set these values to
- Enable Custom Slash Commands
- Enable integrations to override usernames
- Enable integrations to override profile picture icons
- Select Save, but do not close this browser tab, because you need it in a later step.
After you enable custom slash commands in Mattermost, you need configuration information from GitLab. To get this information:
- In a different browser tab than your current Mattermost session, sign in to GitLab as a user with administrator access.
- On the top bar, select Menu > Admin.
- In the left menu, select Settings > Integrations, then select Mattermost slash commands.
- GitLab displays potential values for Mattermost settings. Copy the Request URL as you need it for the next step. All other values are suggestions.
- 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.
To create a slash command, you need the values you obtained from GitLab in the previous step:
- In the Mattermost tab you left open when you enabled custom slash commands, go to your team page.
- Select the Settings icon, and select Integrations.
- In the left menu, select Slash commands.
Select Add Slash Command:
- Provide a Display Name and Description for your new command.
Provide a Command Trigger Word according to your application’s configuration:
If you intend to only connect one project to your Mattermost team: Use
/gitlabfor your trigger word.
If you intend to connect multiple projects: Use a trigger word that relates
to your project, such as
- If you intend to only connect one project to your Mattermost team: Use
- For Request URL, provide the value you copied from GitLab when you viewed configuration values.
- For all other values, you may use the suggestions from GitLab or use your preferred values.
- Copy the Token value, as you need it in a later step, and select Done.
When you create a new slash command in Mattermost, it generates a token you must provide to GitLab:
- In the GitLab browser tab from getting configuration values from GitLab, select the Active checkbox to enable this configuration.
In the Token field, paste the token you obtained from Mattermost. ensure that the Active toggle is enabled.
- Select Save changes for the changes to take effect.
Your slash command can now communicate with your GitLab project.
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.
The available slash commands for Mattermost are:
|/<trigger> issue new <title> ⇧ Shift+↵ Enter <description>||Create a new issue in the project that |
|/<trigger> issue show <issue-number>||Show the issue with ID |
|/<trigger> deploy <environment> to <environment>||Start the CI job that deploys from one environment to another, for example |
To see a list of available commands to interact with GitLab, type the
trigger word followed by help. Example:
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.