From b105e3dcbd5ba4ab5da28dfc68916f543e55da2f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 8 Nov 2016 22:09:38 +0100 Subject: Bring back the old JIRA docs https://gitlab.zendesk.com/agent/tickets/48003 [ci skip] --- doc/project_services/img/builds_emails_service.png | Bin 30956 -> 33943 bytes .../img/jira_add_gitlab_commit_message.png | Bin 0 -> 46590 bytes .../img/jira_add_user_to_group.png | Bin 0 -> 41994 bytes doc/project_services/img/jira_create_new_group.png | Bin 0 -> 32934 bytes .../img/jira_create_new_group_name.png | Bin 0 -> 9054 bytes doc/project_services/img/jira_create_new_user.png | Bin 0 -> 21081 bytes doc/project_services/img/jira_group_access.png | Bin 0 -> 32210 bytes doc/project_services/img/jira_issue_closed.png | Bin 0 -> 77028 bytes doc/project_services/img/jira_issue_reference.png | Bin 0 -> 36188 bytes doc/project_services/img/jira_issues_workflow.png | Bin 0 -> 87067 bytes .../img/jira_merge_request_close.png | Bin 0 -> 102835 bytes doc/project_services/img/jira_project_name.png | Bin 0 -> 41572 bytes ...jira_reference_commit_message_in_jira_issue.png | Bin 0 -> 33706 bytes doc/project_services/img/jira_service.png | Bin 0 -> 56834 bytes .../img/jira_service_close_issue.png | Bin 0 -> 79569 bytes doc/project_services/img/jira_service_page.png | Bin 0 -> 36280 bytes .../img/jira_submit_gitlab_merge_request.png | Bin 0 -> 51913 bytes .../img/jira_user_management_link.png | Bin 0 -> 43095 bytes .../img/jira_workflow_screenshot.png | Bin 0 -> 111093 bytes doc/project_services/jira.md | 247 ++++++++++++++++++++- doc/project_services/project_services.md | 2 +- 21 files changed, 247 insertions(+), 2 deletions(-) create mode 100644 doc/project_services/img/jira_add_gitlab_commit_message.png create mode 100644 doc/project_services/img/jira_add_user_to_group.png create mode 100644 doc/project_services/img/jira_create_new_group.png create mode 100644 doc/project_services/img/jira_create_new_group_name.png create mode 100644 doc/project_services/img/jira_create_new_user.png create mode 100644 doc/project_services/img/jira_group_access.png create mode 100644 doc/project_services/img/jira_issue_closed.png create mode 100644 doc/project_services/img/jira_issue_reference.png create mode 100644 doc/project_services/img/jira_issues_workflow.png create mode 100644 doc/project_services/img/jira_merge_request_close.png create mode 100644 doc/project_services/img/jira_project_name.png create mode 100644 doc/project_services/img/jira_reference_commit_message_in_jira_issue.png create mode 100644 doc/project_services/img/jira_service.png create mode 100644 doc/project_services/img/jira_service_close_issue.png create mode 100644 doc/project_services/img/jira_service_page.png create mode 100644 doc/project_services/img/jira_submit_gitlab_merge_request.png create mode 100644 doc/project_services/img/jira_user_management_link.png create mode 100644 doc/project_services/img/jira_workflow_screenshot.png (limited to 'doc/project_services') diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png index 440728795be..88943dc410e 100644 Binary files a/doc/project_services/img/builds_emails_service.png and b/doc/project_services/img/builds_emails_service.png differ diff --git a/doc/project_services/img/jira_add_gitlab_commit_message.png b/doc/project_services/img/jira_add_gitlab_commit_message.png new file mode 100644 index 00000000000..aec472b9118 Binary files /dev/null and b/doc/project_services/img/jira_add_gitlab_commit_message.png differ diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png new file mode 100644 index 00000000000..0ba737bda9a Binary files /dev/null and b/doc/project_services/img/jira_add_user_to_group.png differ diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png new file mode 100644 index 00000000000..0609060cb05 Binary files /dev/null and b/doc/project_services/img/jira_create_new_group.png differ diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png new file mode 100644 index 00000000000..53d77b17df0 Binary files /dev/null and b/doc/project_services/img/jira_create_new_group_name.png differ diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png new file mode 100644 index 00000000000..9eaa444ed25 Binary files /dev/null and b/doc/project_services/img/jira_create_new_user.png differ diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png new file mode 100644 index 00000000000..8d4657427ae Binary files /dev/null and b/doc/project_services/img/jira_group_access.png differ diff --git a/doc/project_services/img/jira_issue_closed.png b/doc/project_services/img/jira_issue_closed.png new file mode 100644 index 00000000000..acdd83702d3 Binary files /dev/null and b/doc/project_services/img/jira_issue_closed.png differ diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png new file mode 100644 index 00000000000..1a2d9f04a6c Binary files /dev/null and b/doc/project_services/img/jira_issue_reference.png differ diff --git a/doc/project_services/img/jira_issues_workflow.png b/doc/project_services/img/jira_issues_workflow.png new file mode 100644 index 00000000000..0703081d77b Binary files /dev/null and b/doc/project_services/img/jira_issues_workflow.png differ diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png new file mode 100644 index 00000000000..47785e3ba27 Binary files /dev/null and b/doc/project_services/img/jira_merge_request_close.png differ diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png new file mode 100644 index 00000000000..e785ec6140d Binary files /dev/null and b/doc/project_services/img/jira_project_name.png differ 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 new file mode 100644 index 00000000000..fb270d85e3c Binary files /dev/null and b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png differ diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png new file mode 100644 index 00000000000..13aefce6f84 Binary files /dev/null and b/doc/project_services/img/jira_service.png differ diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png new file mode 100644 index 00000000000..eed69e80d2c Binary files /dev/null and b/doc/project_services/img/jira_service_close_issue.png differ diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png new file mode 100644 index 00000000000..a5b49c501ba Binary files /dev/null and b/doc/project_services/img/jira_service_page.png differ diff --git a/doc/project_services/img/jira_submit_gitlab_merge_request.png b/doc/project_services/img/jira_submit_gitlab_merge_request.png new file mode 100644 index 00000000000..77630d39d39 Binary files /dev/null and b/doc/project_services/img/jira_submit_gitlab_merge_request.png differ diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png new file mode 100644 index 00000000000..5f002b59bac Binary files /dev/null and b/doc/project_services/img/jira_user_management_link.png differ diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png new file mode 100644 index 00000000000..937a50a77d9 Binary files /dev/null and b/doc/project_services/img/jira_workflow_screenshot.png differ diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 2ea1c58cb31..b626c746c79 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1 +1,246 @@ -GitLab JIRA integration documentation has moved to [here](../integration/jira.md). +# 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 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 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. + +## Configuration + +The configuration consists of two parts: + +- [JIRA configuration](#configuring-jira) +- [GitLab configuration](#configuring-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 have split this stage in steps so it is easier to follow. + +--- + +1. Login to your JIRA instance as an administrator and under **Administration** + go to **User Management** to create a new user. + + ![JIRA user management link](img/jira_user_management_link.png) + + --- + +1. The next step is to create a new user (e.g., `gitlab`) who has write access + to projects in JIRA. Enter the user's name and a _valid_ e-mail address + since JIRA sends a verification e-mail to set-up the password. + _**Note:** JIRA creates the username automatically by using the e-mail + prefix. You can change it later if you want._ + + ![JIRA create new user](img/jira_create_new_user.png) + + --- + +1. Now, let's create a `gitlab-developers` group which will have write access + to projects in JIRA. Go to the **Groups** tab and select **Create group**. + + ![JIRA create new user](img/jira_create_new_group.png) + + --- + + Give it an optional description and hit **Create group**. + + ![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` + group to JIRA Core. + + ![JIRA group access](img/jira_group_access.png) + + --- + +1. Add the `gitlab` user to the `gitlab-developers` group by going to + **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. + + ![JIRA add user to group](img/jira_add_user_to_group.png) + +--- + +The JIRA configuration is over. Write down the new JIRA username and its +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:///issues/?jql=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:///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:///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:///rest/api/2`. | +| `Username` | The username of the user 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`. | + +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 + +By now you should have [configured JIRA](#configuring-jira) and enabled the +[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly +you should be able to reference and close JIRA issues by just mentioning their +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. + +The same works for comments in merge requests as well. + +![JIRA add GitLab commit message](img/jira_add_gitlab_commit_message.png) + +--- + +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) + +--- + +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 + +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 +followed by the JIRA issue ID in the commit message is pushed, GitLab will +add a comment in the mentioned JIRA issue and immediately close it (provided +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` + +where `GITLAB-1` 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: + +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 + +--- + +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) + +--- + +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) + +--- + +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" + +## Troubleshooting + +### 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. + +### 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. diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 8116a1ce976..4442b7c1742 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -40,7 +40,7 @@ further configuration instructions and details. Contributions are welcome. | Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities | | [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | -| [JIRA](../integration/jira.md) | JIRA issue tracker | +| [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | | 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 | -- cgit v1.2.1 From 55c2c6ce6bfb0966661429fdb91169e52f2cbbbc Mon Sep 17 00:00:00 2001 From: "Z.J. van de Weg" Date: Fri, 18 Nov 2016 14:19:25 +0100 Subject: Add framework for docs on Mattermost commands [ci skip] --- .../img/mattermost_enable_custom_commands.png | Bin 0 -> 42288 bytes doc/project_services/mattermost_command.md | 42 +++++++++++++++++++++ doc/project_services/project_services.md | 1 + 3 files changed, 43 insertions(+) create mode 100644 doc/project_services/img/mattermost_enable_custom_commands.png create mode 100644 doc/project_services/mattermost_command.md (limited to 'doc/project_services') diff --git a/doc/project_services/img/mattermost_enable_custom_commands.png b/doc/project_services/img/mattermost_enable_custom_commands.png new file mode 100644 index 00000000000..a10bda7e190 Binary files /dev/null and b/doc/project_services/img/mattermost_enable_custom_commands.png differ diff --git a/doc/project_services/mattermost_command.md b/doc/project_services/mattermost_command.md new file mode 100644 index 00000000000..1c455c0e891 --- /dev/null +++ b/doc/project_services/mattermost_command.md @@ -0,0 +1,42 @@ +# Mattermost Commands + +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. + +## Configuration + +### On Mattermost + +On Mattermost, an administrator has to enable custom slash commands. To do this, +log on, and go to the system console. + +Click **Custom integrations**, and enable the custom slash commands and don't +forget to save your settings. + +![Enable custom slash commands](img/mattermost_enable_custom_commands.png) + +Now go back to your team page, and go the the configuration page for a new +slash command. + +**Integrations** > **Slash Command** > **Add Slash Command** + +### On GitLab + +On the project you want to configure the slash commands for, go to the +Mattermost Command service. Under settings > **Project Services**. + +A screen will appear with all the values you can copy to the Mattermost page you +have just opened. + +**Insert screenshot here** + +## Usage + +A users first interaction with the newly created slash commands will trigger an +authorisation process. This process connects your Mattermost user with your +GitLab user. + +After these steps are performed, you can start interacting with GitLab. Maybe +start with `/your-trigger issue show 1` and see what your first issue was on +this project! diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 4442b7c1742..93d558df982 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 Commands](mattermost_command.md) | Mattermost 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 | -- cgit v1.2.1 From 0cc4c14514028bead4c668c957cbeb23f4f0f845 Mon Sep 17 00:00:00 2001 From: "Z.J. van de Weg" Date: Mon, 21 Nov 2016 14:52:29 +0100 Subject: Add screenshot in docs [ci skip] --- .../img/mattermost_config_help.png | Bin 0 -> 159971 bytes doc/project_services/mattermost_command.md | 42 --------------------- doc/project_services/mattermost_slash_commands.md | 42 +++++++++++++++++++++ doc/project_services/project_services.md | 2 +- 4 files changed, 43 insertions(+), 43 deletions(-) create mode 100644 doc/project_services/img/mattermost_config_help.png delete mode 100644 doc/project_services/mattermost_command.md create mode 100644 doc/project_services/mattermost_slash_commands.md (limited to 'doc/project_services') diff --git a/doc/project_services/img/mattermost_config_help.png b/doc/project_services/img/mattermost_config_help.png new file mode 100644 index 00000000000..d0b64c058af Binary files /dev/null and b/doc/project_services/img/mattermost_config_help.png differ diff --git a/doc/project_services/mattermost_command.md b/doc/project_services/mattermost_command.md deleted file mode 100644 index 1c455c0e891..00000000000 --- a/doc/project_services/mattermost_command.md +++ /dev/null @@ -1,42 +0,0 @@ -# Mattermost Commands - -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. - -## Configuration - -### On Mattermost - -On Mattermost, an administrator has to enable custom slash commands. To do this, -log on, and go to the system console. - -Click **Custom integrations**, and enable the custom slash commands and don't -forget to save your settings. - -![Enable custom slash commands](img/mattermost_enable_custom_commands.png) - -Now go back to your team page, and go the the configuration page for a new -slash command. - -**Integrations** > **Slash Command** > **Add Slash Command** - -### On GitLab - -On the project you want to configure the slash commands for, go to the -Mattermost Command service. Under settings > **Project Services**. - -A screen will appear with all the values you can copy to the Mattermost page you -have just opened. - -**Insert screenshot here** - -## Usage - -A users first interaction with the newly created slash commands will trigger an -authorisation process. This process connects your Mattermost user with your -GitLab user. - -After these steps are performed, you can start interacting with GitLab. Maybe -start with `/your-trigger issue show 1` and see what your first issue was on -this project! diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md new file mode 100644 index 00000000000..b5cfc77f54a --- /dev/null +++ b/doc/project_services/mattermost_slash_commands.md @@ -0,0 +1,42 @@ +# Mattermost Commands + +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. + +## Configuration + +### On Mattermost + +On Mattermost, an administrator has to enable custom slash commands. To do this, +log on, and go to the system console. + +Click **Custom integrations**, and enable the custom slash commands and don't +forget to save your settings. + +![Enable custom slash commands](img/mattermost_enable_custom_commands.png) + +Now go back to your team page, and go the the configuration page for a new +slash command. + +**Integrations** > **Slash Command** > **Add Slash Command** + +### On GitLab + +On the project you want to configure the slash commands for, go to the +Mattermost Command service. Under settings > **Project Services**. + +A screen will appear with all the values you can copy to the Mattermost page you +have just opened. + +![Mattermost setup instructions](img/mattermost_config_help.png) + +## Usage + +A users first interaction with the newly created slash commands will trigger an +authorisation process. This process connects your Mattermost user with your +GitLab user. + +After these steps are performed, you can start interacting with GitLab. Maybe +start with `/your-trigger issue show 1` and see what your first issue was on +this project! diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 93d558df982..57b731e297b 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -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 | | [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | -| [Mattermost Commands](mattermost_command.md) | Mattermost slash commands | +| [Mattermost Slash Commands](mattermost_slash_commands.md) | Mattermost 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 | -- cgit v1.2.1 From 2a21a347fde928e548b4543fd21ba73633fbb757 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 21 Nov 2016 22:57:03 +0100 Subject: Refactor Mattermost slash commands docs [ci skip] --- .../img/mattermost_add_slash_command.png | Bin 0 -> 23150 bytes doc/project_services/img/mattermost_bot_auth.png | Bin 0 -> 21031 bytes .../img/mattermost_bot_available_commands.png | Bin 0 -> 23504 bytes .../img/mattermost_config_help.png | Bin 159971 -> 176610 bytes .../img/mattermost_console_integrations.png | Bin 0 -> 114850 bytes .../img/mattermost_enable_custom_commands.png | Bin 42288 -> 0 bytes .../img/mattermost_goto_console.png | Bin 0 -> 22802 bytes .../img/mattermost_slash_command_configuration.png | Bin 0 -> 60927 bytes .../img/mattermost_team_integrations.png | Bin 0 -> 12171 bytes doc/project_services/mattermost_slash_commands.md | 134 +++++++++++++++++---- doc/project_services/project_services.md | 2 +- 11 files changed, 112 insertions(+), 24 deletions(-) create mode 100644 doc/project_services/img/mattermost_add_slash_command.png create mode 100644 doc/project_services/img/mattermost_bot_auth.png create mode 100644 doc/project_services/img/mattermost_bot_available_commands.png create mode 100644 doc/project_services/img/mattermost_console_integrations.png delete mode 100644 doc/project_services/img/mattermost_enable_custom_commands.png create mode 100644 doc/project_services/img/mattermost_goto_console.png create mode 100644 doc/project_services/img/mattermost_slash_command_configuration.png create mode 100644 doc/project_services/img/mattermost_team_integrations.png (limited to 'doc/project_services') diff --git a/doc/project_services/img/mattermost_add_slash_command.png b/doc/project_services/img/mattermost_add_slash_command.png new file mode 100644 index 00000000000..6d45bce8004 Binary files /dev/null and b/doc/project_services/img/mattermost_add_slash_command.png differ diff --git a/doc/project_services/img/mattermost_bot_auth.png b/doc/project_services/img/mattermost_bot_auth.png new file mode 100644 index 00000000000..19c4735194f Binary files /dev/null and b/doc/project_services/img/mattermost_bot_auth.png differ diff --git a/doc/project_services/img/mattermost_bot_available_commands.png b/doc/project_services/img/mattermost_bot_available_commands.png new file mode 100644 index 00000000000..04fa4b3ea88 Binary files /dev/null and b/doc/project_services/img/mattermost_bot_available_commands.png differ diff --git a/doc/project_services/img/mattermost_config_help.png b/doc/project_services/img/mattermost_config_help.png index d0b64c058af..3e38bf0abc6 100644 Binary files a/doc/project_services/img/mattermost_config_help.png and b/doc/project_services/img/mattermost_config_help.png differ diff --git a/doc/project_services/img/mattermost_console_integrations.png b/doc/project_services/img/mattermost_console_integrations.png new file mode 100644 index 00000000000..eecec0950a8 Binary files /dev/null and b/doc/project_services/img/mattermost_console_integrations.png differ diff --git a/doc/project_services/img/mattermost_enable_custom_commands.png b/doc/project_services/img/mattermost_enable_custom_commands.png deleted file mode 100644 index a10bda7e190..00000000000 Binary files a/doc/project_services/img/mattermost_enable_custom_commands.png and /dev/null differ diff --git a/doc/project_services/img/mattermost_goto_console.png b/doc/project_services/img/mattermost_goto_console.png new file mode 100644 index 00000000000..3576758b331 Binary files /dev/null and b/doc/project_services/img/mattermost_goto_console.png differ diff --git a/doc/project_services/img/mattermost_slash_command_configuration.png b/doc/project_services/img/mattermost_slash_command_configuration.png new file mode 100644 index 00000000000..06416b0d068 Binary files /dev/null and b/doc/project_services/img/mattermost_slash_command_configuration.png differ diff --git a/doc/project_services/img/mattermost_team_integrations.png b/doc/project_services/img/mattermost_team_integrations.png new file mode 100644 index 00000000000..9086cf1c136 Binary files /dev/null and b/doc/project_services/img/mattermost_team_integrations.png differ diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index b5cfc77f54a..36b72de1be0 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -1,42 +1,130 @@ -# Mattermost Commands +# 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][omnimatdocs]. + ## 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, -log on, and go to the system console. +![Mattermost bot authorize](img/mattermost_bot_auth.png) -Click **Custom integrations**, and enable the custom slash commands and don't -forget to save your settings. +This will connect connect your Mattermost user with your GitLab user. You can +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 -slash command. +## Available slash commands -**Integrations** > **Slash Command** > **Add Slash Command** +The available slash commands so far are: -### On GitLab +- `/ issue create \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 -Mattermost Command service. Under settings > **Project Services**. +If you enabled autocomplete when you created the Mattermost command, you can +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 -authorisation process. This process connects your Mattermost user with your -GitLab user. +The permissions to run the [available commands](#available-commands) derive from +the [permissions you have on the project](../user/permissions.md#project). -After these steps are performed, you can start interacting with GitLab. Maybe -start with `/your-trigger issue show 1` and see what your first issue was on -this project! +[omnimatdocs]: https://docs.gitlab.com/omnibus/gitlab-mattermost/ +[mmslashdocs]: https://docs.mattermost.com/developer/slash-commands.html diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 57b731e297b..cba183c9f15 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -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 | | [JIRA](jira.md) | JIRA issue tracker | | 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) | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | | [Redmine](redmine.md) | Redmine issue tracker | -- cgit v1.2.1 From 25817c2741b988fbd37c2f46e4c0e6cfb8b3764e Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Tue, 22 Nov 2016 11:02:46 +0100 Subject: Restructure steps for MM slash commands service [ci skip] --- .../img/mattermost_bot_available_commands.png | Bin 23504 -> 12746 bytes .../img/mattermost_gitlab_token.png | Bin 0 -> 7879 bytes .../img/mattermost_slash_command_token.png | Bin 0 -> 20415 bytes doc/project_services/mattermost_slash_commands.md | 95 +++++++++++++-------- doc/project_services/project_services.md | 2 +- 5 files changed, 62 insertions(+), 35 deletions(-) create mode 100644 doc/project_services/img/mattermost_gitlab_token.png create mode 100644 doc/project_services/img/mattermost_slash_command_token.png (limited to 'doc/project_services') diff --git a/doc/project_services/img/mattermost_bot_available_commands.png b/doc/project_services/img/mattermost_bot_available_commands.png index 04fa4b3ea88..f912a639cc5 100644 Binary files a/doc/project_services/img/mattermost_bot_available_commands.png and b/doc/project_services/img/mattermost_bot_available_commands.png differ diff --git a/doc/project_services/img/mattermost_gitlab_token.png b/doc/project_services/img/mattermost_gitlab_token.png new file mode 100644 index 00000000000..3f4f26aab35 Binary files /dev/null and b/doc/project_services/img/mattermost_gitlab_token.png differ diff --git a/doc/project_services/img/mattermost_slash_command_token.png b/doc/project_services/img/mattermost_slash_command_token.png new file mode 100644 index 00000000000..320e263026a Binary files /dev/null and b/doc/project_services/img/mattermost_slash_command_token.png differ diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index 36b72de1be0..1507dfa3abd 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -12,7 +12,7 @@ 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]. +[Omnibus GitLab Mattermost documentation][omnimmdocs]. ## Configuration @@ -22,7 +22,7 @@ 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 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 @@ -41,50 +41,74 @@ the administrator console. 1. Click **Save** at the bottom to save the changes. -### Step 2. Create a new custom command in Mattermost +### Step 2. Open the Mattermost slash commands service in GitLab -Now that you have enabled the custom slash commands: +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. -1. Back to your team page settings, you should see the **Integrations** option. + >**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 Command** integration and add a new one by clicking the +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. +1. Fill in the options for the custom command as described in + [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). - ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png) + >**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. - > **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. + ![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**. -> -[**➔ Read more on Mattermost slash commands**][mmslashdocs]. + ![Mattermost slash command token](img/mattermost_slash_command_token.png) -### Step 3. Configure GitLab +### Step 4. Copy the Mattermost token into the Mattermost slash command service -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. +1. In GitLab, paste the Mattermost token you copied in the previous step and + check the **Active** checkbox. - ![Mattermost setup instructions](img/mattermost_config_help.png) + ![Mattermost copy token to GitLab](img/mattermost_gitlab_token.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. +--- + +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, @@ -92,7 +116,7 @@ Mattermost will trigger an authorization process. ![Mattermost bot authorize](img/mattermost_bot_auth.png) -This will connect connect your Mattermost user with your GitLab user. You can +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 @@ -102,18 +126,14 @@ GitLab using the Mattermost commands. The available slash commands so far are: -- `/<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. +| 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` | -If you enabled autocomplete when you created the Mattermost command, you can -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: +To see a list of available commands that can interact with GitLab, type the +trigger word followed by `help`: ``` /my-project help @@ -126,5 +146,12 @@ command trigger word to `my-project`, then to see all available command type: The permissions to run the [available commands](#available-commands) derive from the [permissions you have on the project](../user/permissions.md#project). -[omnimatdocs]: https://docs.gitlab.com/omnibus/gitlab-mattermost/ +## 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 cba183c9f15..890f7525b0e 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -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 | | [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | -| [Mattermost command](mattermost_slash_commands.md) | Mattermost slash commands | +| [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 | -- cgit v1.2.1 From 264eda9f744f82173da4aac756643ac498b5b6a3 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Thu, 17 Nov 2016 13:42:41 +0000 Subject: Revert "Merge branch 'docs/jira-old' into 'master'" This reverts merge request !7365 --- doc/project_services/img/builds_emails_service.png | Bin 33943 -> 30956 bytes .../img/jira_add_gitlab_commit_message.png | Bin 46590 -> 0 bytes .../img/jira_add_user_to_group.png | Bin 41994 -> 0 bytes doc/project_services/img/jira_create_new_group.png | Bin 32934 -> 0 bytes .../img/jira_create_new_group_name.png | Bin 9054 -> 0 bytes doc/project_services/img/jira_create_new_user.png | Bin 21081 -> 0 bytes doc/project_services/img/jira_group_access.png | Bin 32210 -> 0 bytes doc/project_services/img/jira_issue_closed.png | Bin 77028 -> 0 bytes doc/project_services/img/jira_issue_reference.png | Bin 36188 -> 0 bytes doc/project_services/img/jira_issues_workflow.png | Bin 87067 -> 0 bytes .../img/jira_merge_request_close.png | Bin 102835 -> 0 bytes doc/project_services/img/jira_project_name.png | Bin 41572 -> 0 bytes ...jira_reference_commit_message_in_jira_issue.png | Bin 33706 -> 0 bytes doc/project_services/img/jira_service.png | Bin 56834 -> 0 bytes .../img/jira_service_close_issue.png | Bin 79569 -> 0 bytes doc/project_services/img/jira_service_page.png | Bin 36280 -> 0 bytes .../img/jira_submit_gitlab_merge_request.png | Bin 51913 -> 0 bytes .../img/jira_user_management_link.png | Bin 43095 -> 0 bytes .../img/jira_workflow_screenshot.png | Bin 111093 -> 0 bytes doc/project_services/jira.md | 247 +-------------------- doc/project_services/project_services.md | 2 +- 21 files changed, 2 insertions(+), 247 deletions(-) delete mode 100644 doc/project_services/img/jira_add_gitlab_commit_message.png delete mode 100644 doc/project_services/img/jira_add_user_to_group.png delete mode 100644 doc/project_services/img/jira_create_new_group.png delete mode 100644 doc/project_services/img/jira_create_new_group_name.png delete mode 100644 doc/project_services/img/jira_create_new_user.png delete mode 100644 doc/project_services/img/jira_group_access.png delete mode 100644 doc/project_services/img/jira_issue_closed.png delete mode 100644 doc/project_services/img/jira_issue_reference.png delete mode 100644 doc/project_services/img/jira_issues_workflow.png delete mode 100644 doc/project_services/img/jira_merge_request_close.png delete mode 100644 doc/project_services/img/jira_project_name.png delete mode 100644 doc/project_services/img/jira_reference_commit_message_in_jira_issue.png delete mode 100644 doc/project_services/img/jira_service.png delete mode 100644 doc/project_services/img/jira_service_close_issue.png delete mode 100644 doc/project_services/img/jira_service_page.png delete mode 100644 doc/project_services/img/jira_submit_gitlab_merge_request.png delete mode 100644 doc/project_services/img/jira_user_management_link.png delete mode 100644 doc/project_services/img/jira_workflow_screenshot.png (limited to 'doc/project_services') diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png index 88943dc410e..440728795be 100644 Binary files a/doc/project_services/img/builds_emails_service.png and b/doc/project_services/img/builds_emails_service.png differ diff --git a/doc/project_services/img/jira_add_gitlab_commit_message.png b/doc/project_services/img/jira_add_gitlab_commit_message.png deleted file mode 100644 index aec472b9118..00000000000 Binary files a/doc/project_services/img/jira_add_gitlab_commit_message.png and /dev/null differ diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png deleted file mode 100644 index 0ba737bda9a..00000000000 Binary files a/doc/project_services/img/jira_add_user_to_group.png and /dev/null differ diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png deleted file mode 100644 index 0609060cb05..00000000000 Binary files a/doc/project_services/img/jira_create_new_group.png and /dev/null differ diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png deleted file mode 100644 index 53d77b17df0..00000000000 Binary files a/doc/project_services/img/jira_create_new_group_name.png and /dev/null differ diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png deleted file mode 100644 index 9eaa444ed25..00000000000 Binary files a/doc/project_services/img/jira_create_new_user.png and /dev/null differ diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png deleted file mode 100644 index 8d4657427ae..00000000000 Binary files a/doc/project_services/img/jira_group_access.png and /dev/null differ diff --git a/doc/project_services/img/jira_issue_closed.png b/doc/project_services/img/jira_issue_closed.png deleted file mode 100644 index acdd83702d3..00000000000 Binary files a/doc/project_services/img/jira_issue_closed.png and /dev/null differ diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png deleted file mode 100644 index 1a2d9f04a6c..00000000000 Binary files a/doc/project_services/img/jira_issue_reference.png and /dev/null differ diff --git a/doc/project_services/img/jira_issues_workflow.png b/doc/project_services/img/jira_issues_workflow.png deleted file mode 100644 index 0703081d77b..00000000000 Binary files a/doc/project_services/img/jira_issues_workflow.png and /dev/null differ diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png deleted file mode 100644 index 47785e3ba27..00000000000 Binary files a/doc/project_services/img/jira_merge_request_close.png and /dev/null differ diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png deleted file mode 100644 index e785ec6140d..00000000000 Binary files a/doc/project_services/img/jira_project_name.png and /dev/null differ 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 deleted file mode 100644 index fb270d85e3c..00000000000 Binary files a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png and /dev/null differ diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png deleted file mode 100644 index 13aefce6f84..00000000000 Binary files a/doc/project_services/img/jira_service.png and /dev/null differ diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png deleted file mode 100644 index eed69e80d2c..00000000000 Binary files a/doc/project_services/img/jira_service_close_issue.png and /dev/null differ diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png deleted file mode 100644 index a5b49c501ba..00000000000 Binary files a/doc/project_services/img/jira_service_page.png and /dev/null differ diff --git a/doc/project_services/img/jira_submit_gitlab_merge_request.png b/doc/project_services/img/jira_submit_gitlab_merge_request.png deleted file mode 100644 index 77630d39d39..00000000000 Binary files a/doc/project_services/img/jira_submit_gitlab_merge_request.png and /dev/null differ diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png deleted file mode 100644 index 5f002b59bac..00000000000 Binary files a/doc/project_services/img/jira_user_management_link.png and /dev/null differ diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png deleted file mode 100644 index 937a50a77d9..00000000000 Binary files a/doc/project_services/img/jira_workflow_screenshot.png and /dev/null differ diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index b626c746c79..2ea1c58cb31 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1,246 +1 @@ -# 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 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 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. - -## Configuration - -The configuration consists of two parts: - -- [JIRA configuration](#configuring-jira) -- [GitLab configuration](#configuring-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 have split this stage in steps so it is easier to follow. - ---- - -1. Login to your JIRA instance as an administrator and under **Administration** - go to **User Management** to create a new user. - - ![JIRA user management link](img/jira_user_management_link.png) - - --- - -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in JIRA. Enter the user's name and a _valid_ e-mail address - since JIRA sends a verification e-mail to set-up the password. - _**Note:** JIRA creates the username automatically by using the e-mail - prefix. You can change it later if you want._ - - ![JIRA create new user](img/jira_create_new_user.png) - - --- - -1. Now, let's create a `gitlab-developers` group which will have write access - to projects in JIRA. Go to the **Groups** tab and select **Create group**. - - ![JIRA create new user](img/jira_create_new_group.png) - - --- - - Give it an optional description and hit **Create group**. - - ![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` - group to JIRA Core. - - ![JIRA group access](img/jira_group_access.png) - - --- - -1. Add the `gitlab` user to the `gitlab-developers` group by going to - **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. - - ![JIRA add user to group](img/jira_add_user_to_group.png) - ---- - -The JIRA configuration is over. Write down the new JIRA username and its -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). | -| `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`. | - -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 - -By now you should have [configured JIRA](#configuring-jira) and enabled the -[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly -you should be able to reference and close JIRA issues by just mentioning their -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. - -The same works for comments in merge requests as well. - -![JIRA add GitLab commit message](img/jira_add_gitlab_commit_message.png) - ---- - -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) - ---- - -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 - -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 -followed by the JIRA issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned JIRA issue and immediately close it (provided -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` - -where `GITLAB-1` 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: - -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 - ---- - -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) - ---- - -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) - ---- - -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" - -## Troubleshooting - -### 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. - -### 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. +GitLab JIRA integration documentation has moved to [here](../integration/jira.md). diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 890f7525b0e..6b0fc685fd5 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -40,7 +40,7 @@ further configuration instructions and details. Contributions are welcome. | Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities | | [HipChat](hipchat.md) | Private group chat and IM | | [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](../integration/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) | -- cgit v1.2.1 From a478a1dde4e02fcddc41d4e799fed70031162cd0 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Tue, 22 Nov 2016 13:05:58 +0100 Subject: Move JIRA service doc back to its old location --- .../img/jira_add_user_to_group.png | Bin 0 -> 41994 bytes doc/project_services/img/jira_create_new_group.png | Bin 0 -> 32934 bytes .../img/jira_create_new_group_name.png | Bin 0 -> 9054 bytes doc/project_services/img/jira_create_new_user.png | Bin 0 -> 21081 bytes doc/project_services/img/jira_group_access.png | Bin 0 -> 32210 bytes doc/project_services/img/jira_issue_reference.png | Bin 0 -> 49151 bytes .../img/jira_merge_request_close.png | Bin 0 -> 52556 bytes doc/project_services/img/jira_project_name.png | Bin 0 -> 41572 bytes doc/project_services/img/jira_service.png | Bin 0 -> 56834 bytes .../img/jira_service_close_comment.png | Bin 0 -> 29716 bytes .../img/jira_service_close_issue.png | Bin 0 -> 89666 bytes doc/project_services/img/jira_service_page.png | Bin 0 -> 45089 bytes .../img/jira_user_management_link.png | Bin 0 -> 43095 bytes .../img/jira_workflow_screenshot.png | Bin 0 -> 111093 bytes doc/project_services/jira.md | 201 ++++++++++++++++++++- doc/project_services/project_services.md | 2 +- 16 files changed, 201 insertions(+), 2 deletions(-) create mode 100644 doc/project_services/img/jira_add_user_to_group.png create mode 100644 doc/project_services/img/jira_create_new_group.png create mode 100644 doc/project_services/img/jira_create_new_group_name.png create mode 100644 doc/project_services/img/jira_create_new_user.png create mode 100644 doc/project_services/img/jira_group_access.png create mode 100644 doc/project_services/img/jira_issue_reference.png create mode 100644 doc/project_services/img/jira_merge_request_close.png create mode 100644 doc/project_services/img/jira_project_name.png create mode 100644 doc/project_services/img/jira_service.png create mode 100644 doc/project_services/img/jira_service_close_comment.png create mode 100644 doc/project_services/img/jira_service_close_issue.png create mode 100644 doc/project_services/img/jira_service_page.png create mode 100644 doc/project_services/img/jira_user_management_link.png create mode 100644 doc/project_services/img/jira_workflow_screenshot.png (limited to 'doc/project_services') diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png new file mode 100644 index 00000000000..0ba737bda9a Binary files /dev/null and b/doc/project_services/img/jira_add_user_to_group.png differ diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png new file mode 100644 index 00000000000..0609060cb05 Binary files /dev/null and b/doc/project_services/img/jira_create_new_group.png differ diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png new file mode 100644 index 00000000000..53d77b17df0 Binary files /dev/null and b/doc/project_services/img/jira_create_new_group_name.png differ diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png new file mode 100644 index 00000000000..9eaa444ed25 Binary files /dev/null and b/doc/project_services/img/jira_create_new_user.png differ diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png new file mode 100644 index 00000000000..8d4657427ae Binary files /dev/null and b/doc/project_services/img/jira_group_access.png differ diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png new file mode 100644 index 00000000000..463200da6aa Binary files /dev/null and b/doc/project_services/img/jira_issue_reference.png differ diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png new file mode 100644 index 00000000000..b8f6058a514 Binary files /dev/null and b/doc/project_services/img/jira_merge_request_close.png differ diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png new file mode 100644 index 00000000000..e785ec6140d Binary files /dev/null and b/doc/project_services/img/jira_project_name.png differ diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png new file mode 100644 index 00000000000..13aefce6f84 Binary files /dev/null and b/doc/project_services/img/jira_service.png differ diff --git a/doc/project_services/img/jira_service_close_comment.png b/doc/project_services/img/jira_service_close_comment.png new file mode 100644 index 00000000000..84a71c692b1 Binary files /dev/null and b/doc/project_services/img/jira_service_close_comment.png differ diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png new file mode 100644 index 00000000000..b033b210469 Binary files /dev/null and b/doc/project_services/img/jira_service_close_issue.png differ diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png new file mode 100644 index 00000000000..0cc160bebe2 Binary files /dev/null and b/doc/project_services/img/jira_service_page.png differ diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png new file mode 100644 index 00000000000..5f002b59bac Binary files /dev/null and b/doc/project_services/img/jira_user_management_link.png differ diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png new file mode 100644 index 00000000000..937a50a77d9 Binary files /dev/null and b/doc/project_services/img/jira_workflow_screenshot.png differ diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 2ea1c58cb31..4c1b8b2bdd3 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1 +1,200 @@ -GitLab JIRA integration documentation has moved to [here](../integration/jira.md). +# GitLab JIRA integration + +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. + +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. + +Once the project is connected to JIRA, you can reference and close the issues +in JIRA directly from GitLab. + +## Table of Contents +* [Referencing JIRA Issues from GitLab](#referencing-JIRA-issues) +* [Closing JIRA Issues from GitLab](#closing-JIRA-issues) +* [Configuration](#configuration) + +### Referencing JIRA Issues + +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, eg. `PROJECT-7`, will add a comment in JIRA issue in the +format: + +``` + USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: + ENTITY_TITLE +``` + +* `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. + +![example of mentioning or closing the JIRA issue](img/jira_issue_reference.png) + +--- + +### Closing JIRA Issues + +JIRA issues can be closed directly from GitLab by using trigger words, eg. +`Resolves PROJECT-1`, `Closes PROJECT-1` or `Fixes PROJECT-1`, in commits and +merge requests. When a commit which contains the trigger word in the commit +message is pushed, GitLab will add a comment in the mentioned JIRA issue. + +For example, for project named `PROJECT` in JIRA, we implemented a new feature +and created a merge request in GitLab. + +This feature was requested in JIRA issue `PROJECT-7`. Merge request in GitLab +contains the improvement and in merge request description we say that this +merge request `Closes PROJECT-7` issue. + +Once this merge request is merged, the JIRA issue will be automatically closed +with a comment and a associated link to the commit that resolved the issue. + +![A Git commit that causes the JIRA issue to be closed](img/jira_merge_request_close.png) + +--- + +![The GitLab integration closes JIRA issue](img/jira_service_close_issue.png) + +--- + +![The GitLab integration creates a comment and a link on JIRA issue.](img/jira_service_close_comment.png) + + +## Configuration + +### Configuring JIRA + +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. + +--- + +1. Login to your JIRA instance as an administrator and under **Administration** + go to **User Management** to create a new user. + + ![JIRA user management link](img/jira_user_management_link.png) + + --- + +1. The next step is to create a new user (e.g., `gitlab`) who has write access + to projects in JIRA. Enter the user's name and a _valid_ e-mail address + since JIRA sends a verification e-mail to set-up the password. + _**Note:** JIRA creates the username automatically by using the e-mail + prefix. You can change it later if you want._ + + ![JIRA create new user](img/jira_create_new_user.png) + + --- + +1. Now, let's create a `gitlab-developers` group which will have write access + to projects in JIRA. Go to the **Groups** tab and select **Create group**. + + ![JIRA create new user](img/jira_create_new_group.png) + + --- + + Give it an optional description and hit **Create group**. + + ![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` + group to JIRA Core. + + ![JIRA group access](img/jira_group_access.png) + + --- + +1. Add the `gitlab` user to the `gitlab-developers` group by going to + **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. + + ![JIRA add user to group](img/jira_add_user_to_group.png) + +--- + +The JIRA configuration is over. Write down the new JIRA username and its +password as they will be needed when configuring GitLab in the next section. + +### Configuring GitLab + +JIRA configuration in GitLab is done via a project's **Services**. + +#### GitLab 8.13.0 with JIRA v1000.x + +To enable JIRA integration in a project, navigate to the project's +and open the context menu clicking on the top right gear icon, then go to +**Services > JIRA**. + +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. Ex. https://JIRA.example.com | +| `Project key` | The short, all capital letter identifier for your JIRA project. | +| `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 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. + +![JIRA service page](img/jira_service_page.png) + +--- + +#### GitLab 6.x-7.7 with JIRA v6.x + +_**Note:** GitLab versions 8.13.0 and up contain various integration improvements. +We strongly recommend upgrading._ + +In `gitlab.yml` enable the JIRA issue tracker section by +[uncommenting these lines][JIRA-gitlab-yml]. This will make sure that all +issues within GitLab are pointing to the JIRA issue tracker. + +After you set this, you will be able to close issues in JIRA by a commit in +GitLab. + +Go to your project's **Settings** page and fill in the project name for the +JIRA project: + +![Set the JIRA project name in GitLab to 'NEW'](img/jira_project_name.png) + +--- + +You can also enable the JIRA service that will allow you to interact with JIRA +issues. Go to the **Settings > Services > JIRA** and: + +1. Tick the active check box to enable the service +1. Supply the URL to JIRA server, for example http://JIRA.example.com +1. Supply the username of a user we created under `Configuring JIRA` section, + for example `gitlab` +1. Supply the password of the user +1. Optional: supply the JIRA API version, default is version `2` +1. Optional: supply the JIRA issue transition ID (issue transition to closed). + This is dependent on JIRA settings, default is `2` +1. Hit save + + +![JIRA services page](img/jira_service.png) + +[services-templates]: ../project_services/services_templates.md +[JIRA-gitlab-yml]: https://gitlab.com/subscribers/gitlab-ee/blob/6-8-stable-ee/config/gitlab.yml.example#L111-115 diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 6b0fc685fd5..890f7525b0e 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -40,7 +40,7 @@ further configuration instructions and details. Contributions are welcome. | Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities | | [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | -| [JIRA](../integration/jira.md) | JIRA issue tracker | +| [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) | -- cgit v1.2.1 From 33980a0f0cc6c6690f500006d0cb7088a9642530 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Tue, 22 Nov 2016 14:11:48 +0100 Subject: Refactor JIRA docs and bring back some old information --- doc/project_services/img/jira_service_page.png | Bin 45089 -> 30309 bytes doc/project_services/jira.md | 195 +++++++++++++------------ 2 files changed, 101 insertions(+), 94 deletions(-) (limited to 'doc/project_services') diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png index 0cc160bebe2..1cda73be83d 100644 Binary files a/doc/project_services/img/jira_service_page.png and b/doc/project_services/img/jira_service_page.png differ diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 4c1b8b2bdd3..e537a24028c 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -11,64 +11,11 @@ see the [Services Templates][services-templates] document. Once the project is connected to JIRA, you can reference and close the issues in JIRA directly from GitLab. -## Table of Contents -* [Referencing JIRA Issues from GitLab](#referencing-JIRA-issues) -* [Closing JIRA Issues from GitLab](#closing-JIRA-issues) -* [Configuration](#configuration) - -### Referencing JIRA Issues - -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, eg. `PROJECT-7`, will add a comment in JIRA issue in the -format: - -``` - USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: - ENTITY_TITLE -``` - -* `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. - -![example of mentioning or closing the JIRA issue](img/jira_issue_reference.png) - ---- - -### Closing JIRA Issues - -JIRA issues can be closed directly from GitLab by using trigger words, eg. -`Resolves PROJECT-1`, `Closes PROJECT-1` or `Fixes PROJECT-1`, in commits and -merge requests. When a commit which contains the trigger word in the commit -message is pushed, GitLab will add a comment in the mentioned JIRA issue. - -For example, for project named `PROJECT` in JIRA, we implemented a new feature -and created a merge request in GitLab. - -This feature was requested in JIRA issue `PROJECT-7`. Merge request in GitLab -contains the improvement and in merge request description we say that this -merge request `Closes PROJECT-7` issue. - -Once this merge request is merged, the JIRA issue will be automatically closed -with a comment and a associated link to the commit that resolved the issue. - -![A Git commit that causes the JIRA issue to be closed](img/jira_merge_request_close.png) - ---- - -![The GitLab integration closes JIRA issue](img/jira_service_close_issue.png) - ---- - -![The GitLab integration creates a comment and a link on JIRA issue.](img/jira_service_close_comment.png) - - ## Configuration +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 We need to create a user in JIRA which will have access to all projects that @@ -115,7 +62,7 @@ We have split this stage in steps so it is easier to follow. --- 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) @@ -123,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. @@ -136,22 +83,23 @@ password as they will be needed when configuring GitLab in the next section. ### Configuring GitLab -JIRA configuration in GitLab is done via a project's **Services**. - -#### GitLab 8.13.0 with JIRA v1000.x +>**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 the project's -and open the context menu clicking on the top right gear icon, then go to -**Services > JIRA**. - -Fill in the required details on the page as described in the table below. +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. Ex. https://JIRA.example.com | -| `Project key` | The short, all capital letter identifier for your JIRA project. | -| `Username` | The user name created in [configuring JIRA step](#configuring-JIRA). | -| `Password` |The password of the user created in [configuring JIRA step](#configuring-JIRA). | +| `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, the identifier for your JIRA project, all uppercase. | +| `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 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 @@ -161,40 +109,99 @@ with the linked JIRA project. --- -#### GitLab 6.x-7.7 with JIRA v6.x +## JIRA issues + +By now you should have [configured JIRA](#configuring-jira) and enabled the +[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly +you should be able to reference and close JIRA issues by just mentioning their +ID in GitLab commits and merge requests. + +### Referencing JIRA Issues + +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, eg. `PROJECT-7`, will add a comment in JIRA issue in the +format: + +``` +USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: +ENTITY_TITLE +``` + +* `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. + +![example of mentioning or closing the JIRA issue](img/jira_issue_reference.png) + +--- + +### 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 +followed by the JIRA issue ID in the commit message is pushed, GitLab will +add a comment in the mentioned JIRA issue and immediately close it (provided +the transition ID was set up correctly). + +There are currently three trigger words, and you can use either one to achieve +the same goal: -_**Note:** GitLab versions 8.13.0 and up contain various integration improvements. -We strongly recommend upgrading._ +- `Resolves GITLAB-1` +- `Closes GITLAB-1` +- `Fixes GITLAB-1` -In `gitlab.yml` enable the JIRA issue tracker section by -[uncommenting these lines][JIRA-gitlab-yml]. This will make sure that all -issues within GitLab are pointing to the JIRA issue tracker. +- where `GITLAB-1` the issue ID of the JIRA project. -After you set this, you will be able to close issues in JIRA by a commit in -GitLab. +### JIRA issue closing example -Go to your project's **Settings** page and fill in the project name for the -JIRA project: +Let's consider the following example: -![Set the JIRA project name in GitLab to 'NEW'](img/jira_project_name.png) +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. + +![A Git commit that causes the JIRA issue to be closed](img/jira_merge_request_close.png) --- -You can also enable the JIRA service that will allow you to interact with JIRA -issues. Go to the **Settings > Services > JIRA** and: +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 closes JIRA issue](img/jira_service_close_issue.png) + +--- + +![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 -1. Tick the active check box to enable the service -1. Supply the URL to JIRA server, for example http://JIRA.example.com -1. Supply the username of a user we created under `Configuring JIRA` section, - for example `gitlab` -1. Supply the password of the user -1. Optional: supply the JIRA API version, default is version `2` -1. Optional: supply the JIRA issue transition ID (issue transition to closed). - This is dependent on JIRA settings, default is `2` -1. Hit save +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. +### GitLab is unable to close a ticket -![JIRA services page](img/jira_service.png) +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-gitlab-yml]: https://gitlab.com/subscribers/gitlab-ee/blob/6-8-stable-ee/config/gitlab.yml.example#L111-115 +[jira-repo-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/project_services/jira.md -- cgit v1.2.1 From 93792e8da6fe91cfb380eda96bdb83441117be46 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Tue, 22 Nov 2016 18:31:34 +0100 Subject: Add changes to JIRA api docs [ci skip] --- doc/project_services/jira.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/project_services') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index e537a24028c..ef14def78d9 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -97,7 +97,7 @@ 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, the identifier for your JIRA project, all uppercase. | +| `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 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)). | @@ -121,7 +121,7 @@ ID in GitLab commits and merge requests. 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, eg. `PROJECT-7`, will add a comment in JIRA issue in the +referencing an issue, e.g., `PROJECT-7`, will add a comment in JIRA issue in the format: ``` -- cgit v1.2.1 From 7367744401a04b78fa424b5949f688f6c2cb4c7f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Tue, 22 Nov 2016 18:37:21 +0100 Subject: Fix list in JIRA service docs [ci skip] --- doc/project_services/jira.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/project_services') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index ef14def78d9..366e4b2d306 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -150,11 +150,11 @@ 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 -- cgit v1.2.1 From af1dabe805fa7ad6fcdccfdb792b07e00c3c42d2 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis <axilleas@axilleas.me> Date: Tue, 22 Nov 2016 19:53:43 +0100 Subject: Reduce size of images from 25MB to 13MB using pngquant Took it from https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/3232 [ci skip] --- doc/project_services/img/builds_emails_service.png | Bin 30956 -> 19203 bytes .../img/emails_on_push_service.png | Bin 98160 -> 28535 bytes .../img/jira_add_user_to_group.png | Bin 41994 -> 24838 bytes doc/project_services/img/jira_create_new_group.png | Bin 32934 -> 19127 bytes .../img/jira_create_new_group_name.png | Bin 9054 -> 5168 bytes doc/project_services/img/jira_create_new_user.png | Bin 21081 -> 12625 bytes doc/project_services/img/jira_group_access.png | Bin 32210 -> 19235 bytes doc/project_services/img/jira_issue_reference.png | Bin 49151 -> 18399 bytes .../img/jira_merge_request_close.png | Bin 52556 -> 21172 bytes doc/project_services/img/jira_project_name.png | Bin 41572 -> 26685 bytes doc/project_services/img/jira_service.png | Bin 56834 -> 37869 bytes .../img/jira_service_close_comment.png | Bin 29716 -> 11893 bytes .../img/jira_service_close_issue.png | Bin 89666 -> 30570 bytes doc/project_services/img/jira_service_page.png | Bin 30309 -> 12228 bytes .../img/jira_user_management_link.png | Bin 43095 -> 23921 bytes .../img/jira_workflow_screenshot.png | Bin 111093 -> 66685 bytes .../img/mattermost_add_slash_command.png | Bin 23150 -> 9265 bytes doc/project_services/img/mattermost_bot_auth.png | Bin 21031 -> 8676 bytes .../img/mattermost_bot_available_commands.png | Bin 12746 -> 4647 bytes .../img/mattermost_config_help.png | Bin 176610 -> 63138 bytes .../img/mattermost_console_integrations.png | Bin 114850 -> 41186 bytes .../img/mattermost_gitlab_token.png | Bin 7879 -> 3688 bytes .../img/mattermost_goto_console.png | Bin 22802 -> 7754 bytes .../img/mattermost_slash_command_configuration.png | Bin 60927 -> 24169 bytes .../img/mattermost_slash_command_token.png | Bin 20415 -> 8624 bytes .../img/mattermost_team_integrations.png | Bin 12171 -> 4766 bytes doc/project_services/img/redmine_configuration.png | Bin 16973 -> 10266 bytes .../img/services_templates_redmine_example.png | Bin 13936 -> 8776 bytes doc/project_services/img/slack_configuration.png | Bin 75762 -> 29825 bytes 29 files changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/project_services') diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png index 440728795be..9dbbed03833 100644 Binary files a/doc/project_services/img/builds_emails_service.png and b/doc/project_services/img/builds_emails_service.png differ diff --git a/doc/project_services/img/emails_on_push_service.png b/doc/project_services/img/emails_on_push_service.png index cd6f79ad1eb..df301aa1eeb 100644 Binary files a/doc/project_services/img/emails_on_push_service.png and b/doc/project_services/img/emails_on_push_service.png differ diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png index 0ba737bda9a..27dac49260c 100644 Binary files a/doc/project_services/img/jira_add_user_to_group.png and b/doc/project_services/img/jira_add_user_to_group.png differ diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png index 0609060cb05..06c4e84fc61 100644 Binary files a/doc/project_services/img/jira_create_new_group.png and b/doc/project_services/img/jira_create_new_group.png differ diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png index 53d77b17df0..bfc0dc6b2e9 100644 Binary files a/doc/project_services/img/jira_create_new_group_name.png and b/doc/project_services/img/jira_create_new_group_name.png differ diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png index 9eaa444ed25..e9c03ed770d 100644 Binary files a/doc/project_services/img/jira_create_new_user.png and b/doc/project_services/img/jira_create_new_user.png differ diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png index 8d4657427ae..9d64cc57269 100644 Binary files a/doc/project_services/img/jira_group_access.png and b/doc/project_services/img/jira_group_access.png differ diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png index 463200da6aa..72c81460df7 100644 Binary files a/doc/project_services/img/jira_issue_reference.png and b/doc/project_services/img/jira_issue_reference.png differ diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png index b8f6058a514..0f82ceba557 100644 Binary files a/doc/project_services/img/jira_merge_request_close.png and b/doc/project_services/img/jira_merge_request_close.png differ diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png index e785ec6140d..8540a427461 100644 Binary files a/doc/project_services/img/jira_project_name.png and b/doc/project_services/img/jira_project_name.png differ diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png index 13aefce6f84..8e073b84ff9 100644 Binary files a/doc/project_services/img/jira_service.png and b/doc/project_services/img/jira_service.png differ diff --git a/doc/project_services/img/jira_service_close_comment.png b/doc/project_services/img/jira_service_close_comment.png index 84a71c692b1..bb9cd7e3d13 100644 Binary files a/doc/project_services/img/jira_service_close_comment.png and b/doc/project_services/img/jira_service_close_comment.png differ diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png index b033b210469..c85b1d1dd97 100644 Binary files a/doc/project_services/img/jira_service_close_issue.png and b/doc/project_services/img/jira_service_close_issue.png differ diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png index 1cda73be83d..c74351b57b8 100644 Binary files a/doc/project_services/img/jira_service_page.png and b/doc/project_services/img/jira_service_page.png differ diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png index 5f002b59bac..f81c5b5fc87 100644 Binary files a/doc/project_services/img/jira_user_management_link.png and b/doc/project_services/img/jira_user_management_link.png differ diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png index 937a50a77d9..e62fb202613 100644 Binary files a/doc/project_services/img/jira_workflow_screenshot.png and b/doc/project_services/img/jira_workflow_screenshot.png differ diff --git a/doc/project_services/img/mattermost_add_slash_command.png b/doc/project_services/img/mattermost_add_slash_command.png index 6d45bce8004..7759efa183c 100644 Binary files a/doc/project_services/img/mattermost_add_slash_command.png and b/doc/project_services/img/mattermost_add_slash_command.png differ diff --git a/doc/project_services/img/mattermost_bot_auth.png b/doc/project_services/img/mattermost_bot_auth.png index 19c4735194f..830b7849f3d 100644 Binary files a/doc/project_services/img/mattermost_bot_auth.png and b/doc/project_services/img/mattermost_bot_auth.png differ diff --git a/doc/project_services/img/mattermost_bot_available_commands.png b/doc/project_services/img/mattermost_bot_available_commands.png index f912a639cc5..b51798cf10d 100644 Binary files a/doc/project_services/img/mattermost_bot_available_commands.png and b/doc/project_services/img/mattermost_bot_available_commands.png differ diff --git a/doc/project_services/img/mattermost_config_help.png b/doc/project_services/img/mattermost_config_help.png index 3e38bf0abc6..a62e4b792f9 100644 Binary files a/doc/project_services/img/mattermost_config_help.png and b/doc/project_services/img/mattermost_config_help.png differ diff --git a/doc/project_services/img/mattermost_console_integrations.png b/doc/project_services/img/mattermost_console_integrations.png index eecec0950a8..b3b8c20d7bf 100644 Binary files a/doc/project_services/img/mattermost_console_integrations.png and b/doc/project_services/img/mattermost_console_integrations.png differ diff --git a/doc/project_services/img/mattermost_gitlab_token.png b/doc/project_services/img/mattermost_gitlab_token.png index 3f4f26aab35..257018914d2 100644 Binary files a/doc/project_services/img/mattermost_gitlab_token.png and b/doc/project_services/img/mattermost_gitlab_token.png differ diff --git a/doc/project_services/img/mattermost_goto_console.png b/doc/project_services/img/mattermost_goto_console.png index 3576758b331..3354c2a24b4 100644 Binary files a/doc/project_services/img/mattermost_goto_console.png and b/doc/project_services/img/mattermost_goto_console.png differ diff --git a/doc/project_services/img/mattermost_slash_command_configuration.png b/doc/project_services/img/mattermost_slash_command_configuration.png index 06416b0d068..12766ab2b34 100644 Binary files a/doc/project_services/img/mattermost_slash_command_configuration.png and b/doc/project_services/img/mattermost_slash_command_configuration.png differ diff --git a/doc/project_services/img/mattermost_slash_command_token.png b/doc/project_services/img/mattermost_slash_command_token.png index 320e263026a..c38f37c203c 100644 Binary files a/doc/project_services/img/mattermost_slash_command_token.png and b/doc/project_services/img/mattermost_slash_command_token.png differ diff --git a/doc/project_services/img/mattermost_team_integrations.png b/doc/project_services/img/mattermost_team_integrations.png index 9086cf1c136..69d4a231e5a 100644 Binary files a/doc/project_services/img/mattermost_team_integrations.png and b/doc/project_services/img/mattermost_team_integrations.png differ diff --git a/doc/project_services/img/redmine_configuration.png b/doc/project_services/img/redmine_configuration.png index e9d8c0d2da8..7b6dd271401 100644 Binary files a/doc/project_services/img/redmine_configuration.png and b/doc/project_services/img/redmine_configuration.png differ diff --git a/doc/project_services/img/services_templates_redmine_example.png b/doc/project_services/img/services_templates_redmine_example.png index 77c2b98e5d0..50d20510daf 100644 Binary files a/doc/project_services/img/services_templates_redmine_example.png and b/doc/project_services/img/services_templates_redmine_example.png differ diff --git a/doc/project_services/img/slack_configuration.png b/doc/project_services/img/slack_configuration.png index b8de8a56db7..fc8e58e686b 100644 Binary files a/doc/project_services/img/slack_configuration.png and b/doc/project_services/img/slack_configuration.png differ -- cgit v1.2.1 From c1a71d9f58d76973c5ceae3605df1cd3c5f9f287 Mon Sep 17 00:00:00 2001 From: Felipe Artur <felipefac@gmail.com> Date: Wed, 7 Dec 2016 16:00:07 -0200 Subject: Update JIRA troubleshoot documentation --- doc/project_services/jira.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/project_services') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 366e4b2d306..390066c9989 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -197,6 +197,7 @@ incorrectly the JIRA-GitLab integration. 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. +JIRA issue references and update comments will not work if the GitLab issue tracker is disabled. ### GitLab is unable to close a ticket -- cgit v1.2.1 From b9b2ca47b3bcc7dfc56a3199994063988ff8218e Mon Sep 17 00:00:00 2001 From: "Z.J. van de Weg" <git@zjvandeweg.nl> Date: Fri, 9 Dec 2016 09:49:38 +0100 Subject: Update docs to reflect new defaults on omnibus For mattermost chat commands, new defaults are set in the next release making configuring easier. This commit reflects that in the doc. [ci skip] --- .../img/mattermost_console_integrations.png | Bin 41186 -> 314642 bytes doc/project_services/mattermost_slash_commands.md | 8 ++++++-- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'doc/project_services') diff --git a/doc/project_services/img/mattermost_console_integrations.png b/doc/project_services/img/mattermost_console_integrations.png index b3b8c20d7bf..92a30da5be0 100644 Binary files a/doc/project_services/img/mattermost_console_integrations.png and b/doc/project_services/img/mattermost_console_integrations.png differ diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index 1507dfa3abd..6fcbf6f1642 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -22,6 +22,9 @@ commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost +This step is only required when using a source install, omnibus installs will be +preconfigured with the right settings. + The first thing to do in Mattermost is to enable custom slash commands from the administrator console. @@ -32,8 +35,9 @@ the administrator console. --- -1. Click **Custom integrations** and set **Enable Custom Slash Commands** to - true. +1. Click **Custom integrations** and set **Enable Custom Slash Commands**, + **Enable custom integrations to override usernames**, and **Override + custom integrations to override profile picture icons** to true ![Mattermost console](img/mattermost_console_integrations.png) -- cgit v1.2.1 From b7b83fe0c9368fa6f04dcb6eb8cd247978bba76b Mon Sep 17 00:00:00 2001 From: Nick Thomas <nick@gitlab.com> Date: Thu, 8 Dec 2016 16:36:26 +0000 Subject: Introduce deployment services, starting with a KubernetesService --- .../img/kubernetes_configuration.png | Bin 0 -> 113827 bytes doc/project_services/kubernetes.md | 38 +++++++++++++++++++++ doc/project_services/project_services.md | 1 + 3 files changed, 39 insertions(+) create mode 100644 doc/project_services/img/kubernetes_configuration.png create mode 100644 doc/project_services/kubernetes.md (limited to 'doc/project_services') diff --git a/doc/project_services/img/kubernetes_configuration.png b/doc/project_services/img/kubernetes_configuration.png new file mode 100644 index 00000000000..349a2dc8456 Binary files /dev/null and b/doc/project_services/img/kubernetes_configuration.png differ diff --git a/doc/project_services/kubernetes.md b/doc/project_services/kubernetes.md new file mode 100644 index 00000000000..cb577b608b4 --- /dev/null +++ b/doc/project_services/kubernetes.md @@ -0,0 +1,38 @@ +# GitLab Kubernetes / OpenShift integration + +GitLab can be configured to interact with Kubernetes, or other systems using the +Kubernetes API (such as OpenShift). + +Each project can be configured to connect to a different Kubernetes cluster, see +the [configuration](#configuration) section. + +If you have a single cluster that you want to use for all your projects, +you can pre-fill the settings page with a default template. To configure the +template, see the [Services Templates](services-templates.md) document. + +## Configuration + +![Kubernetes configuration settings](img/kubernetes_configuration.png) + +The Kubernetes service takes the following arguments: + +1. Kubernetes namespace +1. API URL +1. Service token +1. Custom CA bundle + +The API URL is the URL that GitLab uses to access the Kubernetes API. Kubernetes +exposes several APIs - we want the "base" URL that is common to all of them, +e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + +GitLab authenticates against Kubernetes using service tokens, which are +scoped to a particular `namespace`. If you don't have a service token yet, +you can follow the +[Kubernetes documentation](http://kubernetes.io/docs/user-guide/service-accounts/) +to create one. You can also view or create service tokens in the +[Kubernetes dashboard](http://kubernetes.io/docs/user-guide/ui/) - visit +`Config -> Secrets`. + +Fill in the service token and namespace according to the values you just got. +If the API is using a self-signed TLS certificate, you'll also need to include +the `ca.crt` contents as the `Custom CA bundle`. diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 890f7525b0e..a7bcd186a8c 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 | +| [Kubernetes](kubernetes.md) | A containerized deployment service | | [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 | -- cgit v1.2.1 From 141faaacf9119ce5d765efe73c6509030ba078cd Mon Sep 17 00:00:00 2001 From: Felipe Artur <felipefac@gmail.com> Date: Fri, 25 Nov 2016 17:36:37 -0200 Subject: Mattermost Notifications Service --- .../img/mattermost_configuration.png | Bin 0 -> 73502 bytes doc/project_services/mattermost.md | 45 +++++++++++++++++++++ doc/project_services/project_services.md | 3 +- doc/project_services/slack.md | 4 +- 4 files changed, 49 insertions(+), 3 deletions(-) create mode 100644 doc/project_services/img/mattermost_configuration.png create mode 100644 doc/project_services/mattermost.md (limited to 'doc/project_services') diff --git a/doc/project_services/img/mattermost_configuration.png b/doc/project_services/img/mattermost_configuration.png new file mode 100644 index 00000000000..3c5ff5ee317 Binary files /dev/null and b/doc/project_services/img/mattermost_configuration.png differ diff --git a/doc/project_services/mattermost.md b/doc/project_services/mattermost.md new file mode 100644 index 00000000000..fbc7dfeee6d --- /dev/null +++ b/doc/project_services/mattermost.md @@ -0,0 +1,45 @@ +# Mattermost Notifications Service + +## On Mattermost + +To enable Mattermost integration you must create an incoming webhook integration: + +1. Sign in to your Mattermost instance +1. Visit incoming webhooks, that will be something like: https://mattermost.example/your_team_name/integrations/incoming_webhooks/add +1. Choose a display name, description and channel, those can be overridden on GitLab +1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. + +There might be some cases that Incoming Webhooks are blocked by admin, ask your mattermost admin to enable +it on https://mattermost.example/admin_console/integrations/custom. + +Display name override is not enabled by default, you need to ask your admin to enable it on that same section. + +## On GitLab + +After you set up Mattermost, it's time to set up GitLab. + +Go to your project's **Settings > Services > Mattermost Notifications** and you will see a +checkbox with the following events that can be triggered: + +- Push +- Issue +- Merge request +- Note +- Tag push +- Build +- Wiki page + +Bellow each of these event checkboxes, you will have an input field to insert +which Mattermost channel you want to send that event message, with `#town-square` +being the default. The hash sign is optional. + +At the end, fill in your Mattermost details: + +| Field | Description | +| ----- | ----------- | +| **Webhook** | The incoming webhooks which you have to setup on Mattermost, it will be something like: http://mattermost.example/hooks/5xo... | +| **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | +| **Notify only broken builds** | If you choose to enable the **Build** event and you want to be only notified about failed builds. | + + +![Mattermost configuration](img/mattermost_configuration.png) diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index a7bcd186a8c..0f398874b8f 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -44,10 +44,11 @@ further configuration instructions and details. Contributions are welcome. | JetBrains TeamCity CI | A continuous integration and build server | | [Kubernetes](kubernetes.md) | A containerized deployment service | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | +| [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | +| [Slack Notifications](slack.md) | Receive event notifications in Slack | | 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 | -| [Slack](slack.md) | A team communication tool for the 21st century | ## Services Templates diff --git a/doc/project_services/slack.md b/doc/project_services/slack.md index 3cfe77c9f85..0b682b43810 100644 --- a/doc/project_services/slack.md +++ b/doc/project_services/slack.md @@ -1,4 +1,4 @@ -# Slack Service +# Slack Notifications Service ## On Slack @@ -15,7 +15,7 @@ Slack: After you set up Slack, it's time to set up GitLab. -Go to your project's **Settings > Services > Slack** and you will see a +Go to your project's **Settings > Services > Slack Notifications** and you will see a checkbox with the following events that can be triggered: - Push -- cgit v1.2.1 From ef7fd97901c3f3820f08f93f97dd8fdbf0616648 Mon Sep 17 00:00:00 2001 From: Pedro Moreira da Silva <pedro@gitlab.com> Date: Wed, 30 Nov 2016 16:30:03 +0000 Subject: Update Mattermost slash commands docs to explain how to create a newline and use <kbd> for user input. See HTML5 spec: https://www.w3.org/TR/html5/text-level-semantics.html#the-kbd-element --- doc/project_services/mattermost_slash_commands.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) (limited to 'doc/project_services') diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index 6fcbf6f1642..a4d2618e567 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -65,7 +65,7 @@ the administrator console. ### Step 3. Create a new custom slash command in Mattermost -Now that you have enabled the custom slash commands in Mattermost and opened +Now that you have enabled 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. @@ -128,20 +128,16 @@ GitLab using the Mattermost commands. ## Available slash commands -The available slash commands so far are: +The available slash commands 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` | +| <kbd>/<trigger> issue create <title> **Shift** + **Enter** <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | <samp>/gitlab issue create We need to change the homepage</samp> | +| <kbd>/<trigger> issue show <issue-number></kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | <samp>/gitlab issue show 42</samp> | +| <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured][ciyaml]. | <samp>/gitlab deploy staging to production</samp> | -To see a list of available commands that can interact with GitLab, type the -trigger word followed by `help`: - -``` -/my-project help -``` +To see a list of available commands to interact with GitLab, type the +trigger word followed by <kbd>help</kbd>. Example: <samp>/gitlab help</samp> ![Mattermost bot available commands](img/mattermost_bot_available_commands.png) -- cgit v1.2.1 From 70e72e8938b169f88e5b014500a9afeb6ff66a2b Mon Sep 17 00:00:00 2001 From: Pedro Moreira da Silva <pedro@gitlab.com> Date: Thu, 15 Dec 2016 13:11:43 +0000 Subject: Rename `issue create` slash command to `issue new` --- doc/project_services/mattermost_slash_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/project_services') diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index a4d2618e567..1a7c13a29b4 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -132,7 +132,7 @@ The available slash commands are: | Command | Description | Example | | ------- | ----------- | ------- | -| <kbd>/<trigger> issue create <title> **Shift** + **Enter** <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | <samp>/gitlab issue create We need to change the homepage</samp> | +| <kbd>/<trigger> issue new <title> <kbd>⇧ Shift</kbd>+<kbd>↵ Enter</kbd> <description></kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | <samp>/gitlab issue new We need to change the homepage</samp> | | <kbd>/<trigger> issue show <issue-number></kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | <samp>/gitlab issue show 42</samp> | | <kbd>/<trigger> deploy <environment> to <environment></kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured][ciyaml]. | <samp>/gitlab deploy staging to production</samp> | -- cgit v1.2.1 From c945a0a7141ddf80e58e821178195cc48b8143f0 Mon Sep 17 00:00:00 2001 From: Adam Niedzielski <adamsunday@gmail.com> Date: Fri, 16 Dec 2016 13:24:03 +0100 Subject: Pass variables from deployment project services to CI runner This commit introduces the concept of deployment variables - variables that are collected from deployment services and passed to CI runner during a deployment build. Deployment services specify the variables by overriding "predefined_variables" method. This commit also configures variables for KubernetesService --- doc/project_services/kubernetes.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'doc/project_services') diff --git a/doc/project_services/kubernetes.md b/doc/project_services/kubernetes.md index cb577b608b4..fda364b864e 100644 --- a/doc/project_services/kubernetes.md +++ b/doc/project_services/kubernetes.md @@ -36,3 +36,14 @@ to create one. You can also view or create service tokens in the Fill in the service token and namespace according to the values you just got. If the API is using a self-signed TLS certificate, you'll also need to include the `ca.crt` contents as the `Custom CA bundle`. + +## Deployment variables + +The Kubernetes service exposes following +[deployment variables](../ci/variables/README.md#deployment-variables) in the +GitLab CI build environment: + +- `KUBE_URL` - equal to the API URL +- `KUBE_TOKEN` +- `KUBE_NAMESPACE` +- `KUBE_CA_PEM` - only if a custom CA bundle was specified -- cgit v1.2.1