diff options
Diffstat (limited to 'doc/project_services')
37 files changed, 238 insertions, 119 deletions
diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png Binary files differindex 88943dc410e..9dbbed03833 100644 --- a/doc/project_services/img/builds_emails_service.png +++ b/doc/project_services/img/builds_emails_service.png diff --git a/doc/project_services/img/emails_on_push_service.png b/doc/project_services/img/emails_on_push_service.png Binary files differindex cd6f79ad1eb..df301aa1eeb 100644 --- a/doc/project_services/img/emails_on_push_service.png +++ b/doc/project_services/img/emails_on_push_service.png diff --git a/doc/project_services/img/jira_add_gitlab_commit_message.png b/doc/project_services/img/jira_add_gitlab_commit_message.png Binary files differdeleted file mode 100644 index aec472b9118..00000000000 --- a/doc/project_services/img/jira_add_gitlab_commit_message.png +++ /dev/null diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png Binary files differindex 0ba737bda9a..27dac49260c 100644 --- a/doc/project_services/img/jira_add_user_to_group.png +++ b/doc/project_services/img/jira_add_user_to_group.png diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png Binary files differindex 0609060cb05..06c4e84fc61 100644 --- a/doc/project_services/img/jira_create_new_group.png +++ b/doc/project_services/img/jira_create_new_group.png diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png Binary files differindex 53d77b17df0..bfc0dc6b2e9 100644 --- a/doc/project_services/img/jira_create_new_group_name.png +++ b/doc/project_services/img/jira_create_new_group_name.png diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png Binary files differindex 9eaa444ed25..e9c03ed770d 100644 --- a/doc/project_services/img/jira_create_new_user.png +++ b/doc/project_services/img/jira_create_new_user.png diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png Binary files differindex 8d4657427ae..9d64cc57269 100644 --- a/doc/project_services/img/jira_group_access.png +++ b/doc/project_services/img/jira_group_access.png diff --git a/doc/project_services/img/jira_issue_closed.png b/doc/project_services/img/jira_issue_closed.png Binary files differdeleted file mode 100644 index acdd83702d3..00000000000 --- a/doc/project_services/img/jira_issue_closed.png +++ /dev/null diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png Binary files differindex 1a2d9f04a6c..72c81460df7 100644 --- a/doc/project_services/img/jira_issue_reference.png +++ b/doc/project_services/img/jira_issue_reference.png diff --git a/doc/project_services/img/jira_issues_workflow.png b/doc/project_services/img/jira_issues_workflow.png Binary files differdeleted file mode 100644 index 0703081d77b..00000000000 --- a/doc/project_services/img/jira_issues_workflow.png +++ /dev/null diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png Binary files differindex 47785e3ba27..0f82ceba557 100644 --- a/doc/project_services/img/jira_merge_request_close.png +++ b/doc/project_services/img/jira_merge_request_close.png diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png Binary files differindex e785ec6140d..8540a427461 100644 --- a/doc/project_services/img/jira_project_name.png +++ b/doc/project_services/img/jira_project_name.png diff --git a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png Binary files differdeleted file mode 100644 index fb270d85e3c..00000000000 --- a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png +++ /dev/null diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png Binary files differindex 13aefce6f84..8e073b84ff9 100644 --- a/doc/project_services/img/jira_service.png +++ b/doc/project_services/img/jira_service.png diff --git a/doc/project_services/img/jira_service_close_comment.png b/doc/project_services/img/jira_service_close_comment.png Binary files differnew file mode 100644 index 00000000000..bb9cd7e3d13 --- /dev/null +++ b/doc/project_services/img/jira_service_close_comment.png diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png Binary files differindex eed69e80d2c..c85b1d1dd97 100644 --- a/doc/project_services/img/jira_service_close_issue.png +++ b/doc/project_services/img/jira_service_close_issue.png diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png Binary files differindex a5b49c501ba..c74351b57b8 100644 --- a/doc/project_services/img/jira_service_page.png +++ b/doc/project_services/img/jira_service_page.png diff --git a/doc/project_services/img/jira_submit_gitlab_merge_request.png b/doc/project_services/img/jira_submit_gitlab_merge_request.png Binary files differdeleted file mode 100644 index 77630d39d39..00000000000 --- a/doc/project_services/img/jira_submit_gitlab_merge_request.png +++ /dev/null diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png Binary files differindex 5f002b59bac..f81c5b5fc87 100644 --- a/doc/project_services/img/jira_user_management_link.png +++ b/doc/project_services/img/jira_user_management_link.png diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png Binary files differindex 937a50a77d9..e62fb202613 100644 --- a/doc/project_services/img/jira_workflow_screenshot.png +++ b/doc/project_services/img/jira_workflow_screenshot.png diff --git a/doc/project_services/img/mattermost_add_slash_command.png b/doc/project_services/img/mattermost_add_slash_command.png Binary files differnew file mode 100644 index 00000000000..7759efa183c --- /dev/null +++ b/doc/project_services/img/mattermost_add_slash_command.png diff --git a/doc/project_services/img/mattermost_bot_auth.png b/doc/project_services/img/mattermost_bot_auth.png Binary files differnew file mode 100644 index 00000000000..830b7849f3d --- /dev/null +++ b/doc/project_services/img/mattermost_bot_auth.png diff --git a/doc/project_services/img/mattermost_bot_available_commands.png b/doc/project_services/img/mattermost_bot_available_commands.png Binary files differnew file mode 100644 index 00000000000..b51798cf10d --- /dev/null +++ b/doc/project_services/img/mattermost_bot_available_commands.png diff --git a/doc/project_services/img/mattermost_config_help.png b/doc/project_services/img/mattermost_config_help.png Binary files differnew file mode 100644 index 00000000000..a62e4b792f9 --- /dev/null +++ b/doc/project_services/img/mattermost_config_help.png diff --git a/doc/project_services/img/mattermost_console_integrations.png b/doc/project_services/img/mattermost_console_integrations.png Binary files differnew file mode 100644 index 00000000000..b3b8c20d7bf --- /dev/null +++ b/doc/project_services/img/mattermost_console_integrations.png diff --git a/doc/project_services/img/mattermost_gitlab_token.png b/doc/project_services/img/mattermost_gitlab_token.png Binary files differnew file mode 100644 index 00000000000..257018914d2 --- /dev/null +++ b/doc/project_services/img/mattermost_gitlab_token.png diff --git a/doc/project_services/img/mattermost_goto_console.png b/doc/project_services/img/mattermost_goto_console.png Binary files differnew file mode 100644 index 00000000000..3354c2a24b4 --- /dev/null +++ b/doc/project_services/img/mattermost_goto_console.png diff --git a/doc/project_services/img/mattermost_slash_command_configuration.png b/doc/project_services/img/mattermost_slash_command_configuration.png Binary files differnew file mode 100644 index 00000000000..12766ab2b34 --- /dev/null +++ b/doc/project_services/img/mattermost_slash_command_configuration.png diff --git a/doc/project_services/img/mattermost_slash_command_token.png b/doc/project_services/img/mattermost_slash_command_token.png Binary files differnew file mode 100644 index 00000000000..c38f37c203c --- /dev/null +++ b/doc/project_services/img/mattermost_slash_command_token.png diff --git a/doc/project_services/img/mattermost_team_integrations.png b/doc/project_services/img/mattermost_team_integrations.png Binary files differnew file mode 100644 index 00000000000..69d4a231e5a --- /dev/null +++ b/doc/project_services/img/mattermost_team_integrations.png diff --git a/doc/project_services/img/redmine_configuration.png b/doc/project_services/img/redmine_configuration.png Binary files differindex e9d8c0d2da8..7b6dd271401 100644 --- a/doc/project_services/img/redmine_configuration.png +++ b/doc/project_services/img/redmine_configuration.png diff --git a/doc/project_services/img/services_templates_redmine_example.png b/doc/project_services/img/services_templates_redmine_example.png Binary files differindex 77c2b98e5d0..50d20510daf 100644 --- a/doc/project_services/img/services_templates_redmine_example.png +++ b/doc/project_services/img/services_templates_redmine_example.png diff --git a/doc/project_services/img/slack_configuration.png b/doc/project_services/img/slack_configuration.png Binary files differindex b8de8a56db7..fc8e58e686b 100644 --- a/doc/project_services/img/slack_configuration.png +++ b/doc/project_services/img/slack_configuration.png diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index b626c746c79..366e4b2d306 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1,36 +1,31 @@ # GitLab JIRA integration ->**Note:** -Full JIRA integration was previously exclusive to GitLab Enterprise Edition. -With [GitLab 8.3 forward][8_3_post], this feature in now [backported][jira-ce] -to GitLab Community Edition as well. +GitLab can be configured to interact with JIRA. Configuration happens via +user name and password. Connecting to a JIRA server via CAS is not possible. ---- - -GitLab can be configured to interact with [JIRA Core] either using an -on-premises instance or the SaaS solution that Atlassian offers. Configuration -happens via username and password on a per-project basis. Connecting to a JIRA -server via CAS is not possible. +Each project can be configured to connect to a different JIRA instance, see the +[configuration](#configuration) section. If you have one JIRA instance you can +pre-fill the settings page with a default template. To configure the template +see the [Services Templates][services-templates] document. -Each project can be configured to connect to a different JIRA instance or, in -case you have a single JIRA instance, you can pre-fill the JIRA service -settings page in GitLab with a default template. To configure the JIRA template, -see the [Services Templates documentation][services-templates]. - -Once the GitLab project is connected to JIRA, you can reference and close the -issues in JIRA directly from GitLab's merge requests. +Once the project is connected to JIRA, you can reference and close the issues +in JIRA directly from GitLab. ## Configuration -The configuration consists of two parts: - -- [JIRA configuration](#configuring-jira) -- [GitLab configuration](#configuring-gitlab) +In order to enable the JIRA service in GitLab, you need to first configure the +project in JIRA and then enter the correct values in GitLab. ### Configuring JIRA -First things first, we need to create a user in JIRA which will have access to -all projects that need to integrate with GitLab. +We need to create a user in JIRA which will have access to all projects that +need to integrate with GitLab. Login to your JIRA instance as admin and under +Administration go to User Management and create a new user. + +As an example, we'll create a user named `gitlab` and add it to `JIRA-developers` +group. + +**It is important that the user `GitLab` has write-access to projects in JIRA** We have split this stage in steps so it is easier to follow. @@ -62,12 +57,12 @@ We have split this stage in steps so it is easier to follow. Give it an optional description and hit **Create group**. - ![JIRA create new group](img/jira_create_new_group_name.png) + ![jira create new group](img/jira_create_new_group_name.png) --- 1. Give the newly-created group write access by going to - **Application access > View configuration** and adding the `gitlab-developers` + **Application access ➔ View configuration** and adding the `gitlab-developers` group to JIRA Core. ![JIRA group access](img/jira_group_access.png) @@ -75,7 +70,7 @@ We have split this stage in steps so it is easier to follow. --- 1. Add the `gitlab` user to the `gitlab-developers` group by going to - **Users > GitLab user > Add group** and selecting the `gitlab-developers` + **Users ➔ GitLab user ➔ Add group** and selecting the `gitlab-developers` group from the dropdown menu. Notice that the group says _Access_ which is what we aim for. @@ -88,50 +83,30 @@ password as they will be needed when configuring GitLab in the next section. ### Configuring GitLab ->**Note:** -The currently supported JIRA versions are v6.x and v7.x. and GitLab -7.8 or higher is required. - ---- - -Assuming you [have already configured JIRA](#configuring-jira), now it's time -to configure GitLab. - -JIRA configuration in GitLab is done via a project's -[**Services**](../project_services/project_services.md). - -To enable JIRA integration in a project, navigate to the project's -**Settings > Services > JIRA**. - -Fill in the required details on the page, as described in the table below. - -| Setting | Description | -| ------- | ----------- | -| `Description` | A name for the issue tracker (to differentiate between instances, for example). | -| `Project url` | The URL to the JIRA project which is being linked to this GitLab project. It is of the form: `https://<jira_host_url>/issues/?jql=project=<jira_project>`. | -| `Issues url` | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. It is of the form: `https://<jira_host_url>/browse/:id`. Leave `:id` as-is, it gets replaced by GitLab at runtime. | -| `New issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project, and it is of the form: `https://<jira_host_url>/secure/CreateIssue.jspa` | -| `Api url` | The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`. It is of the form: `https://<jira_host_url>/rest/api/2`. | -| `Username` | The username of the user created in [configuring JIRA step](#configuring-jira). | +>**Notes:** +- The currently supported JIRA versions are `v6.x` and `v7.x.`. GitLab 7.8 or + higher is required. +- GitLab 8.14 introduced a new way to integrate with JIRA which greatly simplified + the configuration options you have to enter. If you are using an older version, + [follow this documentation][jira-repo-docs]. + +To enable JIRA integration in a project, navigate to your project's +**Services ➔ JIRA** and fill in the required details on the page as described +in the table below. + +| Field | Description | +| ----- | ----------- | +| `URL` | The base URL to the JIRA project which is being linked to this GitLab project. E.g., `https://jira.example.com`. | +| `Project key` | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. | +| `Username` | The user name created in [configuring JIRA step](#configuring-jira). | | `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | -| `JIRA issue transition` | This setting is very important to set up correctly. It is the ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. | +| `JIRA issue transition` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). | After saving the configuration, your GitLab project will be able to interact with the linked JIRA project. -For example, given the settings below: - -- the JIRA URL is `https://jira.example.com` -- the project is named `GITLAB` -- the user is named `gitlab` -- the JIRA issue transition is 151 (based on the [JIRA issue transition][trans]) - -the following screenshot shows how the JIRA service settings should look like. - ![JIRA service page](img/jira_service_page.png) -[trans]: img/jira_issues_workflow.png - --- ## JIRA issues @@ -143,36 +118,28 @@ ID in GitLab commits and merge requests. ### Referencing JIRA Issues -If you reference a JIRA issue, e.g., `GITLAB-1`, in a commit comment, a link -which points back to JIRA is created. +When GitLab project has JIRA issue tracker configured and enabled, mentioning +JIRA issue in GitLab will automatically add a comment in JIRA issue with the +link back to GitLab. This means that in comments in merge requests and commits +referencing an issue, e.g., `PROJECT-7`, will add a comment in JIRA issue in the +format: -The same works for comments in merge requests as well. +``` +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: +ENTITY_TITLE +``` -![JIRA add GitLab commit message](img/jira_add_gitlab_commit_message.png) - ---- +* `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. +* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where JIRA issue was mentioned. +* `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. +* `PROJECT_NAME` GitLab project name. +* `ENTITY_TITLE` Merge request title or commit message first line. -The mentioning action is two-fold, so a comment with a JIRA issue in GitLab -will automatically add a comment in that particular JIRA issue with the link -back to GitLab. - - -![JIRA reference commit message](img/jira_reference_commit_message_in_jira_issue.png) +![example of mentioning or closing the JIRA issue](img/jira_issue_reference.png) --- -The comment on the JIRA issue is of the form: - -> USER mentioned this issue in LINK_TO_THE_MENTION - -Where: - -| Format | Description | -| ------ | ----------- | -| `USER` | A user that mentioned the issue. This is the link to the user profile in GitLab. | -| `LINK_TO_THE_MENTION` | Link to the origin of mention with a name of the entity where JIRA issue was mentioned. Can be commit or merge request. | - -### Closing JIRA issues +### Closing JIRA Issues JIRA issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word @@ -183,64 +150,58 @@ the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve the same goal: -- `Resolves GITLAB-1` -- `Closes GITLAB-1` -- `Fixes GITLAB-1` +- `Resolves PROJECT-1` +- `Closes PROJECT-1` +- `Fixes PROJECT-1` -where `GITLAB-1` the issue ID of the JIRA project. +where `PROJECT-1` is the issue ID of the JIRA project. ### JIRA issue closing example -Let's say for example that we submitted a bug fix and created a merge request -in GitLab. The workflow would be something like this: +Let's consider the following example: -1. Create a new branch -1. Fix the bug -1. Commit the changes and push branch to GitLab -1. Open a new merge request and reference the JIRA issue including one of the - trigger words, e.g.: `Fixes GITLAB-1`, in the description -1. Submit the merge request -1. Ask someone to review -1. Merge the merge request -1. The JIRA issue is automatically closed +1. For the project named `PROJECT` in JIRA, we implemented a new feature + and created a merge request in GitLab. +1. This feature was requested in JIRA issue `PROJECT-7` and the merge request + in GitLab contains the improvement +1. In the merge request description we use the issue closing trigger + `Closes PROJECT-7`. +1. Once the merge request is merged, the JIRA issue will be automatically closed + with a comment and an associated link to the commit that resolved the issue. --- In the following screenshot you can see what the link references to the JIRA issue look like. -![JIRA - submit a GitLab merge request](img/jira_submit_gitlab_merge_request.png) +![A Git commit that causes the JIRA issue to be closed](img/jira_merge_request_close.png) --- Once this merge request is merged, the JIRA issue will be automatically closed with a link to the commit that resolved the issue. -![The GitLab integration user leaves a comment on JIRA](img/jira_issue_closed.png) +![The GitLab integration closes JIRA issue](img/jira_service_close_issue.png) --- -You can see from the above image that there are four references to GitLab: - -- The first is from a comment in a specific commit -- The second is from the JIRA issue reference in the merge request description -- The third is from the actual commit that solved the issue -- And the fourth is from the commit that the merge request created - -[services-templates]: ../project_services/services_templates.md "Services templates documentation" -[JIRA Core]: https://www.atlassian.com/software/jira/core "The JIRA Core website" -[jira-ce]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2146 "MR - Backport JIRA service" -[8_3_post]: https://about.gitlab.com/2015/12/22/gitlab-8-3-released/ "GitLab 8.3 release post" +![The GitLab integration creates a comment and a link on JIRA issue.](img/jira_service_close_comment.png) ## Troubleshooting +If things don't work as expected that's usually because you have configured +incorrectly the JIRA-GitLab integration. + ### GitLab is unable to comment on a ticket Make sure that the user you set up for GitLab to communicate with JIRA has the -correct access permission to post comments on a ticket and to also transition the -ticket, if you'd like GitLab to also take care of closing them. +correct access permission to post comments on a ticket and to also transition +the ticket, if you'd like GitLab to also take care of closing them. ### GitLab is unable to close a ticket -Make sure the the `Transition ID` you set within the JIRA settings matches the -one your project needs to close a ticket. +Make sure the `Transition ID` you set within the JIRA settings matches the one +your project needs to close a ticket. + +[services-templates]: ../project_services/services_templates.md +[jira-repo-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/project_services/jira.md diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md new file mode 100644 index 00000000000..1507dfa3abd --- /dev/null +++ b/doc/project_services/mattermost_slash_commands.md @@ -0,0 +1,157 @@ +# Mattermost slash commands + +> Introduced in GitLab 8.14 + +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 +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][omnimmdocs]. + +## Configuration + +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 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. Open the Mattermost slash commands service in GitLab + +1. Open a new tab for GitLab and go to your project's settings + **Services ➔ Mattermost command**. A screen will appear with all the values you + need to copy in Mattermost as described in the next step. Leave the window open. + + >**Note:** + GitLab will propose some values for the Mattermost settings. The only one + required to copy-paste as-is is the **Request URL**, all the others are just + suggestions. + + ![Mattermost setup instructions](img/mattermost_config_help.png) + + --- + +1. Proceed to the next step and create a slash command in Mattermost with the + above values. + +### Step 3. Create a new custom slash command in Mattermost + +Now that you have enabled the custom slash commands in Mattermost and opened +the Mattermost slash commands service in GitLab, it's time to copy these values +in a new slash command. + +1. Back to Mattermost, under your team page settings, you should see the + **Integrations** option. + + ![Mattermost team integrations](img/mattermost_team_integrations.png) + + --- + +1. Go to the **Slash Commands** 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 as described in + [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). + + >**Note:** + If you plan on connecting multiple projects, pick a slash command trigger + word that relates to your projects such as `/gitlab-project-name` or even + just `/project-name`. Only use `/gitlab` if you will only connect a single + project to your Mattermost team. + + ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png) + +1. After you setup all the values, copy the token (we will use it below) and + click **Done**. + + ![Mattermost slash command token](img/mattermost_slash_command_token.png) + +### Step 4. Copy the Mattermost token into the Mattermost slash command service + +1. In GitLab, paste the Mattermost token you copied in the previous step and + check the **Active** checkbox. + + ![Mattermost copy token to GitLab](img/mattermost_gitlab_token.png) + +1. Click **Save changes** for the changes to take effect. + +--- + +You are now set to start using slash commands in Mattermost that talk to the +GitLab project you configured. + +## 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. + +![Mattermost bot authorize](img/mattermost_bot_auth.png) + +This will connect 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 so far are: + +| Command | Description | Example | +| ------- | ----------- | ------- | +| `/<trigger> issue create <title>\n<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/trigger issue create 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. | `/trigger 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][ciyaml]. | `/trigger deploy staging to production` | + +To see a list of available commands that can interact with GitLab, type the +trigger word followed by `help`: + +``` +/my-project help +``` + +![Mattermost bot available commands](img/mattermost_bot_available_commands.png) + +## Permissions + +The permissions to run the [available commands](#available-commands) derive from +the [permissions you have on the project](../user/permissions.md#project). + +## Further reading + +- [Mattermost slash commands documentation][mmslashdocs] +- [Omnibus GitLab Mattermost][omnimmdocs] + + +[omnimmdocs]: https://docs.gitlab.com/omnibus/gitlab-mattermost/ +[mmslashdocs]: https://docs.mattermost.com/developer/slash-commands.html +[ciyaml]: ../ci/yaml/README.md diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 4442b7c1742..890f7525b0e 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -42,6 +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 | | [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | +| [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | 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 | | [Redmine](redmine.md) | Redmine issue tracker | |