From 5637423c698d373232f70af91e13bd16610510ac Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 10:08:44 +0100 Subject: Split JIRA configuration for GitLab < 7.8 and > 7.8 [ci skip] --- doc/project_services/jira.md | 122 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 doc/project_services/jira.md (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md new file mode 100644 index 00000000000..3e0129bfe37 --- /dev/null +++ b/doc/project_services/jira.md @@ -0,0 +1,122 @@ +# GitLab JIRA integration + +GitLab can be configured to interact with JIRA. Configuration happens via +username 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. + +## Configuration + +The configuration consists of two parts: + +- [JIRA configuration](#configuring-jira) +- [GitLab configuration](#configuring-gitlab) + +### 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** + +### Configuring GitLab + +JIRA configuration in GitLab is done via a project's +[**Services**](../project_services/project_services.md). + +#### GitLab 7.8 and up + +_The currently supported JIRA versions are v6.x and v7.x._ + +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. + +| Field | Description | +| ----- | ----------- | +| `description` | A name for the issue tracker (to differentiate between instances, for instance). | +| `project url` | The URL to the JIRA project which is being linked to this GitLab project. | +| `issues url` | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. | +| `new issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project. | +| `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`, i.e. `https://jira.example.com/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 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)). By default, this ID is `2` (in the example image, this is `2` as well) | + +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 7.8 and up contain various integration improvements. +We strongly recommend upgrading._ + +In the unfortunate event that you are still using GitLab < 7.8, consult the +[jira_old document](jira_old.md) on how to configure JIRA. + +## JIRA issues + +### 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 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. | + +![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 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 user leaves a comment on JIRA](img/jira_service_close_issue.png) + +--- + +[services-templates]: ../project_services/services_templates.md -- cgit v1.2.1 From d5fc2e9ded87579c588972da5e53f635e4f1d36d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 13:48:36 +0100 Subject: Add steps on configuring JIRA [ci skip] --- doc/project_services/jira.md | 75 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 13 deletions(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 3e0129bfe37..65d850934bb 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1,15 +1,15 @@ # GitLab JIRA integration -GitLab can be configured to interact with JIRA. Configuration happens via +GitLab can be configured to interact with [JIRA]. Configuration happens via username 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. +Each project can be configured to connect to a different JIRA instance or, in +case you have one JIRA instance, you can pre-fill the JIRA service settings page +with a default template. To configure the template, see the +[Services Templates documentation][services-templates]. Once the project is connected to JIRA, you can reference and close the issues -in JIRA directly from GitLab. +in JIRA directly from GitLab's Merge requests. ## Configuration @@ -20,14 +20,62 @@ The configuration consists of two parts: ### 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. +First things first, we need to create a user in JIRA which will have access to +all projects that need to integrate with GitLab. -As an example, we'll create a user named `gitlab` and add it to `jira-developers` -group. +We have split this stage in steps so it could be easier to follow. -**It is important that the user `gitlab` has write-access to projects in JIRA** +--- + +1. Login to your JIRA instance as an administrator and under **Administration** + go to **User Management** and 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 in + order to set-up their password. + _**Note:** JIRA creates the username automatically by using the e-mail + prefix. You can change the username 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 `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. Note the new user `gitlab` and its password as +they will be needed when configuring GitLab in the next section. ### Configuring GitLab @@ -119,4 +167,5 @@ with a link to the commit that resolved the issue. --- -[services-templates]: ../project_services/services_templates.md +[services-templates]: ../project_services/services_templates.md "Services templates documentation" +[JIRA]: https://www.atlassian.com/software/jira/core "The JIRA Core website" -- cgit v1.2.1 From 0fcf3adabb84bf62b374916615cde276d2c61843 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 20:29:52 +0100 Subject: JIRA doc clean-up [ci skip] - Add GitLab configuration steps - Add example workflow - Replace old images with new ones --- doc/project_services/jira.md | 144 ++++++++++++++++++++++++++++--------------- 1 file changed, 94 insertions(+), 50 deletions(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 65d850934bb..564a3cc9336 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1,15 +1,17 @@ # GitLab JIRA integration -GitLab can be configured to interact with [JIRA]. Configuration happens via -username and password. Connecting to a JIRA server via CAS is not possible. +GitLab can be configured to interact with [JIRA Core] either using an +on-premises instance or the SaaS solution that Atlassian offers. Configuration +happens via username and password on a per-project basis. Connecting to a JIRA +server via CAS is not possible. Each project can be configured to connect to a different JIRA instance or, in -case you have one JIRA instance, you can pre-fill the JIRA service settings page -with a default template. To configure the template, see the -[Services Templates documentation][services-templates]. +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 project is connected to JIRA, you can reference and close the issues -in JIRA directly from GitLab's Merge requests. +Once the GitLab project is connected to JIRA, you can reference and close the +issues in JIRA directly from GitLab's Merge requests. ## Configuration @@ -28,17 +30,17 @@ We have split this stage in steps so it could be easier to follow. --- 1. Login to your JIRA instance as an administrator and under **Administration** - go to **User Management** and create a new user. + 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 in - order to set-up their password. + 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 the username later if you want._ + prefix. You can change it later if you want._ ![JIRA create new user](img/jira_create_new_user.png) @@ -74,33 +76,36 @@ We have split this stage in steps so it could be easier to follow. --- -The JIRA configuration is over. Note the new user `gitlab` and its password as -they will be needed when configuring GitLab in the next section. +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 +## Configuring GitLab + +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). #### GitLab 7.8 and up -_The currently supported JIRA versions are v6.x and v7.x._ +_**Note:** The currently supported JIRA versions are v6.x and v7.x._ 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. +Fill in the required details on the page, as described in the table below. -| Field | Description | -| ----- | ----------- | -| `description` | A name for the issue tracker (to differentiate between instances, for instance). | -| `project url` | The URL to the JIRA project which is being linked to this GitLab project. | -| `issues url` | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. | -| `new issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project. | -| `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`, i.e. `https://jira.example.com/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 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)). By default, this ID is `2` (in the example image, this is `2` as well) | +| 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's 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 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](img/jira_issues_workflow.png)). 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. @@ -119,17 +124,38 @@ In the unfortunate event that you are still using GitLab < 7.8, consult the ## 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 JIRA issues 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: +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 -``` +> USER mentioned this issue in LINK_TO_THE_MENTION Where: @@ -138,34 +164,52 @@ Where: | `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. | -![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. -### Closing JIRA Issues +There are currently three trigger words, and you can use either one to achieve +the same goal: -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. +- `Resolves GITLAB-1` +- `Closes GITLAB-1` +- `Fixes GITLAB-1` -For example, for project named `PROJECT` in JIRA, we implemented a new feature -and created a merge request in GitLab. +where `GITLAB-1` the issue ID of the JIRA project. -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. +### JIRA issue closing example -Once this merge request is merged, the JIRA issue will be automatically closed -with a link to the commit that resolved the issue. +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 back 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 -![A Git commit that causes the JIRA issue to be closed](img/jira_merge_request_close.png) +--- + +In the following screenshot you can see how 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_service_close_issue.png) --- [services-templates]: ../project_services/services_templates.md "Services templates documentation" -[JIRA]: https://www.atlassian.com/software/jira/core "The JIRA Core website" +[JIRA Core]: https://www.atlassian.com/software/jira/core "The JIRA Core website" -- cgit v1.2.1 From 6c46b79d9a959a9dc74748f6cb3d30fa5ff89264 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 20:36:12 +0100 Subject: Fix sub-heading [ci skip] --- doc/project_services/jira.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 564a3cc9336..2ade54aeaf8 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -79,7 +79,7 @@ We have split this stage in steps so it could be easier to follow. 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 +### Configuring GitLab Assuming you [have already configured JIRA](#configuring-jira), now it's time to configure GitLab. -- cgit v1.2.1 From c53aad315f89e0eaa44ab680d0b79f38c4590083 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 22:17:41 +0100 Subject: Add proper screenshot and comment on the output [ci skip] --- doc/project_services/jira.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 2ade54aeaf8..b82e4857814 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -167,9 +167,10 @@ Where: ### 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. +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: @@ -187,7 +188,7 @@ in GitLab. The workflow would be something like this: 1. Create a new branch 1. Fix the bug -1. Commit the changes and push back to GitLab +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 @@ -207,9 +208,17 @@ issue look like. 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_service_close_issue.png) +![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 one 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 one 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" -- cgit v1.2.1 From 81d79c7f0a8e8bd54cf39a886ab89ec4532f34b1 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 23:52:04 +0100 Subject: Fix typos, grammar and styling --- doc/project_services/jira.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index b82e4857814..c733e4b2e9b 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -11,7 +11,7 @@ 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. +issues in JIRA directly from GitLab's merge requests. ## Configuration @@ -25,7 +25,7 @@ The configuration consists of two parts: 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 could be easier to follow. +We have split this stage in steps so it is easier to follow. --- @@ -36,7 +36,7 @@ We have split this stage in steps so it could be easier to follow. --- -1. The next step is to create a new user (e.g., `gitlab`) who has write-access +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 @@ -46,7 +46,7 @@ We have split this stage in steps so it could be easier to follow. --- -1. Now, let's create a `gitlab-developers` group which will have write-access +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) @@ -67,7 +67,7 @@ We have split this stage in steps so it could be easier to follow. --- -1. Add the `gitlab` user to `gitlab-developers` group by going to +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. @@ -99,9 +99,9 @@ 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's of the form: `https:///issues/?jql=project=`. | +| `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 is of the form: `https:///secure/CreateIssue.jspa` | +| `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). | @@ -126,12 +126,8 @@ In the unfortunate event that you are still using GitLab < 7.8, consult the 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 JIRA issues and -- close JIRA issues - -by just mentioning their ID in GitLab commits and merge requests. +you should be able to reference JIRA issues and close JIRA issues by just +mentioning their ID in GitLab commits and merge requests. ### Referencing JIRA Issues @@ -198,7 +194,7 @@ in GitLab. The workflow would be something like this: --- -In the following screenshot you can see how the link references to the JIRA +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) @@ -215,10 +211,9 @@ with a link to the commit that resolved the issue. 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 one is from the JIRA issue reference in the merge request - description +- 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 one is from the commit that the merge request created +- 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" -- cgit v1.2.1 From fbc988de54e7e87cde2828a43942181907a42c7d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 23:59:28 +0100 Subject: Remove old JIRA reference --- doc/project_services/jira.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index c733e4b2e9b..17b9d59d439 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -81,16 +81,14 @@ 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._ + 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). -#### GitLab 7.8 and up - -_**Note:** The currently supported JIRA versions are v6.x and v7.x._ - To enable JIRA integration in a project, navigate to the project's **Settings > Services > JIRA**. @@ -114,14 +112,6 @@ with the linked JIRA project. --- -#### GitLab 6.x-7.7 with JIRA v6.x - -_**Note:** GitLab versions 7.8 and up contain various integration improvements. -We strongly recommend upgrading._ - -In the unfortunate event that you are still using GitLab < 7.8, consult the -[jira_old document](jira_old.md) on how to configure JIRA. - ## JIRA issues By now you should have [configured JIRA](#configuring-jira) and enabled the -- cgit v1.2.1 From 229845947f09e158937f114e0cedf486252bdda5 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 25 Jan 2016 23:59:49 +0100 Subject: Add minimum required GitLab version [ci skip] --- doc/project_services/jira.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'doc/project_services/jira.md') diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 17b9d59d439..d6b2e7f521b 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -81,7 +81,10 @@ 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._ +_**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. @@ -116,8 +119,8 @@ with the linked JIRA project. 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 JIRA issues and close JIRA issues by just -mentioning their ID in GitLab commits and merge requests. +you should be able to reference and close JIRA issues by just mentioning their +ID in GitLab commits and merge requests. ### Referencing JIRA Issues -- cgit v1.2.1