Commit 2a21a347 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Refactor Mattermost slash commands docs

[ci skip]
parent 0cc4c145
# Mattermost Commands # Mattermost slash commands
> Introduced in GitLab 8.14
Mattermost commands give users an extra interface to perform common operations Mattermost commands give users an extra interface to perform common operations
from the chat environment. This allows one to, for example, create an issue as from the chat environment. This allows one to, for example, create an issue as
soon as the idea was discussed in Mattermost. soon as the idea was discussed in Mattermost.
## Prerequisites
Mattermost 3.4 and up is required.
If you have the Omnibus GitLab package installed, Mattermost is already bundled
in it. All you have to do is configure it. Read more in the
[Omnibus GitLab Mattermost documentation][omnimatdocs].
## Configuration ## Configuration
### On Mattermost The configuration consists of two parts. First you need to enable the slash
commands in Mattermost and then enable the service in GitLab.
### Step 1. Enable custom slash commands in Mattermost
The first thing to do in Mattermost is to enable the custom slash commands from
the administrator console.
1. Log in with an account that has admin privileges and navigate to the system
console.
![Mattermost go to console](img/mattermost_goto_console.png)
---
1. Click **Custom integrations** and set **Enable Custom Slash Commands** to
true.
![Mattermost console](img/mattermost_console_integrations.png)
---
1. Click **Save** at the bottom to save the changes.
### Step 2. Create a new custom command in Mattermost
Now that you have enabled the custom slash commands:
1. Back to your team page settings, you should see the **Integrations** option.
![Mattermost team integrations](img/mattermost_team_integrations.png)
---
1. Go to the **Slash Command** integration and add a new one by clicking the
**Add Slash Command** button.
![Mattermost add command](img/mattermost_add_slash_command.png)
---
1. Fill in the options for the custom command.
![Mattermost add command configuration](img/mattermost_slash_command_configuration.png)
> **Note:**
When configuring the GitLab Mattermost command service in the next step,
you will be presented with some predefined values to paste into the
Mattermost slash command settings.
1. After you setup all the values, copy the token (we will use it below) and
click **Done**.
>
[**➔ Read more on Mattermost slash commands**][mmslashdocs].
### Step 3. Configure GitLab
1. Go to your project's settings **Services ➔ Mattermost command**. A screen
will appear with all the values you can copy to the Mattermost page in the
previous step.
![Mattermost setup instructions](img/mattermost_config_help.png)
1. Paste the Mattermost token you copied when setting up the Mattermost slash
command and check the **Active** checkbox.
1. Click **Save changes** for the changes to take effect.
## Authorizing Mattermost to interact with GitLab
The first time a user will interact with the newly created slash commands,
Mattermost will trigger an authorization process.
On Mattermost, an administrator has to enable custom slash commands. To do this, ![Mattermost bot authorize](img/mattermost_bot_auth.png)
log on, and go to the system console.
Click **Custom integrations**, and enable the custom slash commands and don't This will connect connect your Mattermost user with your GitLab user. You can
forget to save your settings. see all authorized chat accounts in your profile's page under **Chat**.
![Enable custom slash commands](img/mattermost_enable_custom_commands.png) When the authorization process is complete, you can start interacting with
GitLab using the Mattermost commands.
Now go back to your team page, and go the the configuration page for a new ## Available slash commands
slash command.
**Integrations** > **Slash Command** > **Add Slash Command** The available slash commands so far are:
### On GitLab - `/<trigger> issue create <title>\n<description>` - Create a new issue to the
project that `<trigger>` is tied to.
- `/<trigger> issue show <issue-number>` - Show the issue with ID `<issue-number>`
from the project that `<trigger>` is tied to.
- `/<trigger> deploy <environment> to <environment>` - Start the CI job that
deploys from an environment to another, for example `staging` to `production`.
CI must be properly configured.
On the project you want to configure the slash commands for, go to the If you enabled autocomplete when you created the Mattermost command, you can
Mattermost Command service. Under settings > **Project Services**. use the autocomplete hint to see the available commands that can interact
with GitLab. If for example the autocomplete hint was set to `help` and the
command trigger word to `my-project`, then to see all available command type:
A screen will appear with all the values you can copy to the Mattermost page you ```
have just opened. /my-project help
```
![Mattermost setup instructions](img/mattermost_config_help.png) ![Mattermost bot available commands](img/mattermost_bot_available_commands.png)
## Usage ## Permissions
A users first interaction with the newly created slash commands will trigger an The permissions to run the [available commands](#available-commands) derive from
authorisation process. This process connects your Mattermost user with your the [permissions you have on the project](../user/permissions.md#project).
GitLab user.
After these steps are performed, you can start interacting with GitLab. Maybe [omnimatdocs]: https://docs.gitlab.com/omnibus/gitlab-mattermost/
start with `/your-trigger issue show 1` and see what your first issue was on [mmslashdocs]: https://docs.mattermost.com/developer/slash-commands.html
this project!
...@@ -42,7 +42,7 @@ further configuration instructions and details. Contributions are welcome. ...@@ -42,7 +42,7 @@ further configuration instructions and details. Contributions are welcome.
| [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway |
| [JIRA](jira.md) | JIRA issue tracker | | [JIRA](jira.md) | JIRA issue tracker |
| JetBrains TeamCity CI | A continuous integration and build server | | JetBrains TeamCity CI | A continuous integration and build server |
| [Mattermost Slash Commands](mattermost_slash_commands.md) | Mattermost slash commands | | [Mattermost command](mattermost_slash_commands.md) | Mattermost slash commands |
| PivotalTracker | Project Management Software (Source Commits Endpoint) | | PivotalTracker | Project Management Software (Source Commits Endpoint) |
| Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop |
| [Redmine](redmine.md) | Redmine issue tracker | | [Redmine](redmine.md) | Redmine issue tracker |
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment