From QuickBuild 3, a two-way solution is provided to integrate with Atlassian JIRA. The integration features:
* Hyperlink the JIRA keys in commit messages to corresponding JIRA pages
* Generate an issues report from commit messages
* Progress/update the issues from commit messages
* Release a version of a project in JIRA and update the fixed versions field of issues with status fixed or closed
* Create an issue to JIRA based on a customized step condition
* View SCM changes for each issue
* View related builds for each issue
* View related builds for each project
This page will describe how to integrate JIRA in QuickBuild.
*On This Page*
{toc:class=pagetoc|style=disc|indent=20px|maxLevel=3}
{info}
Supported JIRA version should be JIRA 3.13.3 or higher.
{info}
h3. Simple Integration
To enable the integration:
*1. Enable 'Access remote API calls' in JIRA Administration*
!jira-remote-calls.png!
*2. Configure JIRA server in your configuration setting tab*
!jira-server-setting.png!
You can associate multiple JIRA projects with one QuickBuild configuration. The first project defined will be the *primary project* which means it has the strongest associations with the configuration. When you want to release version to JIRA, this project will be used, and when build version is managed by JIRA, this project will also be used to retrieve the unreleased versions. See details about release version step below.
After doing these, the issues keys mentioned in commit messages will be hyperlinked:
!Working With Issue Tracker^issues-overview.png!
and an issues report tab will be displayed in Build tab:
!Working With Issue Tracker^issues-tab.png!
you can also find all related issues from a specified version and view the changes for an issue:
!Working With Issue Tracker^issues-history.png!
After configured the JIRA server in the configuration settings, below steps are available to add in your build workflow:
* Update Issue Step
* Release Version Step
* Create Issue Step
!jira-steps.png!
h3. Update Issues Via Commit Command
To update issues from the commit messages, *Update JIRA Issue* step should be added to your build workflow. And when QuickBuild find any [commit commands|Commit Command] in the commit message, QuickBuild will execute these commands to update or progress the issues listed in the commands.
*NOTE:*
* To update issues, the user defined in JIRA server should has the proper rights or you will be not able to update the issues.
* This step should be defined after your checkout step.
* QuickBuild will update all issues which are requested from the commit comments from *previous successful* build.
* If issue updated manually after committed, this issue will not be updated then.
* Only issues which belong to the projects defined in JIRA server will be updated.
* The user defined in JIRA server should have full permissions to do the related workflow transitions.
*Customize Commit Command*
The [commit command|Commit Command] has two types:
* Progress Command which is used to progress an issue in the JIRA workflow
* Update Command which is used to update an issue only and will not lead to a workflow transition and use _*update*_ as the command name.
The progress commands can be customized in the Update Jira Issue step based on your JIRA workflow definition.
!commit-commands.png!
*Command Attributes*
A [commit command|Commit Command] has below attributes, each attribute relates to the field of an issue:
||Attribute||Description||
|summary|The summary of an issue|
|description|The description of an issue|
|type|The issue type|
|priority|The issue priority|
|reporter|The reporter of an issue|
|assignee|The assignee of an issue|
|environment|The environment field of an issue|
|affectsVersions|The affects versions field of an issue|
|fixVersions|The fixed versions field of an issue|
|comment|Add a comment to an issue|
|time|{note}
To use time attribute, [time tracking|http://confluence.atlassian.com/display/JIRA/Logging+Work+on+an+Issue] must be enabled in your JIRA server. Please check with your JIRA administrator, if you cannot record time tracking information against issues.
{note}
Records the time tracking information of an issue. The syntax for time is:
{code}
<n>w <n>d <n>h <n>m <worklog comment>
{code}
Here, _<n>_ is user specified time period. For example: 1w 2d 3h 20m Total cost period - this will record 1 week 2 days 3 hours and 20 minutes against the issue and add the comment 'Total cost period' in the Work Log tab of the issue.
|
JIRA custom fields are also supported, for custom fields, below format can be used:
{code}
customfield_10000
or just
10000
{code}
here, *10000* is the field id of a custom field. Please reference http://confluence.atlassian.com/display/JIRA/Custom+fields for details about custom field or consult your JIRA administrator for the custom field id.
Below we will give some example commit messages to illustrate the commit commands:
* In below commit message, QuickBuild will resolve the issues TST-1 and TST-2 and add comment _The issue has been fixed_ to both issues.
{code}
1. Modified Foo.java to fix TST-1, TST-2 --comment The issue has been fixed
2. Some dummy comments ...
{code}
* In below commit message, QuickBuild will add _2d 3h_ to the worklog and add comment _Some comment_ to issue TST-1. The value of time _2d 3h_ should be used the format defined in JIRA time tracking.
{code}
Update TST-1 --time 2d 3h --comment Some comment
{code}
* In below commit message, the value of custom field 10000 will be updated to _for custom field1_ and custom field 10001
{code}
Update TST-1 --customfield_10000 for custom field1 --10001 for custom field2
{code}
will be updated to _for custom field2_.
You can define common attributes in the Update Jira Issue step so that when updating issues, the attributes can be applied to all of the issues. When an attribute is specified both in [commit command|Commit Command] and _Extra Attributes_, the value in commit command will be used.
!extra-attributes.png!
h3. Release QuickBuild Version to JIRA
By adding *_Release JIRA Version_* step, QuickBuild can release current build version to primary project defined in configuration settings -> JIRA Server. If this version is not existed, QuickBuild will create it automatically. Also, this step will find all closed or resolved issues in the primary project which were mentioned in commit messages and then update the Fix Version/s field of them.
{note}
* The issues should be in the primary project (first project defined in associated project keys in configuration settings -> JIRA Server
* The user defined in JIRA Setting must have global or project administrator rights in order to release version.
* Only the issues in the primary project will be updated.
{note}
The version can be managed either from QuickBuild or from JIRA:
h4. Manage From QuickBuild
By default, the version is managed by QuickBuild, that means you need not define any version for the associated project in JIRA and QuickBuild will automatically create and release the JIRA version.
h4. Manage From JIRA
Also, you can manage the version from JIRA and use JIRA version as your build version.
{note}
TBD
{note}
h3. Create Issue From QuickBuild
You may create an issue from QuickBuild by adding a *_Create JIRA Issue_* step. A common case is that when build failed, create an issue so that we can track the build from JIRA.
h3. Trouble Shooting
* Q: I can't add comment to a closed issue, why?
A: You need modify the file $JIRA_HOME/atlassian-jira/WEB-INF/classes/jira-workflow.xml, find 'Closed' step and change the value of 'jira.issue.editable' to *true*.
* Q: The commit command failed with error: Workflow step 'Start Progress' is not valid for issue: ABC-123, but I can progress this issue directly from Jira GUI.
A: The user defined in JIRA server should have the permissions to do all of the workflow actions which defined in workflow command transition. If you encountered the problems above, please login to Jira with that user and check the 'Available Workflow Actions' section.
* Hyperlink the JIRA keys in commit messages to corresponding JIRA pages
* Generate an issues report from commit messages
* Progress/update the issues from commit messages
* Release a version of a project in JIRA and update the fixed versions field of issues with status fixed or closed
* Create an issue to JIRA based on a customized step condition
* View SCM changes for each issue
* View related builds for each issue
* View related builds for each project
This page will describe how to integrate JIRA in QuickBuild.
*On This Page*
{toc:class=pagetoc|style=disc|indent=20px|maxLevel=3}
{info}
Supported JIRA version should be JIRA 3.13.3 or higher.
{info}
h3. Simple Integration
To enable the integration:
*1. Enable 'Access remote API calls' in JIRA Administration*
!jira-remote-calls.png!
*2. Configure JIRA server in your configuration setting tab*
!jira-server-setting.png!
You can associate multiple JIRA projects with one QuickBuild configuration. The first project defined will be the *primary project* which means it has the strongest associations with the configuration. When you want to release version to JIRA, this project will be used, and when build version is managed by JIRA, this project will also be used to retrieve the unreleased versions. See details about release version step below.
After doing these, the issues keys mentioned in commit messages will be hyperlinked:
!Working With Issue Tracker^issues-overview.png!
and an issues report tab will be displayed in Build tab:
!Working With Issue Tracker^issues-tab.png!
you can also find all related issues from a specified version and view the changes for an issue:
!Working With Issue Tracker^issues-history.png!
After configured the JIRA server in the configuration settings, below steps are available to add in your build workflow:
* Update Issue Step
* Release Version Step
* Create Issue Step
!jira-steps.png!
h3. Update Issues Via Commit Command
To update issues from the commit messages, *Update JIRA Issue* step should be added to your build workflow. And when QuickBuild find any [commit commands|Commit Command] in the commit message, QuickBuild will execute these commands to update or progress the issues listed in the commands.
*NOTE:*
* To update issues, the user defined in JIRA server should has the proper rights or you will be not able to update the issues.
* This step should be defined after your checkout step.
* QuickBuild will update all issues which are requested from the commit comments from *previous successful* build.
* If issue updated manually after committed, this issue will not be updated then.
* Only issues which belong to the projects defined in JIRA server will be updated.
* The user defined in JIRA server should have full permissions to do the related workflow transitions.
*Customize Commit Command*
The [commit command|Commit Command] has two types:
* Progress Command which is used to progress an issue in the JIRA workflow
* Update Command which is used to update an issue only and will not lead to a workflow transition and use _*update*_ as the command name.
The progress commands can be customized in the Update Jira Issue step based on your JIRA workflow definition.
!commit-commands.png!
*Command Attributes*
A [commit command|Commit Command] has below attributes, each attribute relates to the field of an issue:
||Attribute||Description||
|summary|The summary of an issue|
|description|The description of an issue|
|type|The issue type|
|priority|The issue priority|
|reporter|The reporter of an issue|
|assignee|The assignee of an issue|
|environment|The environment field of an issue|
|affectsVersions|The affects versions field of an issue|
|fixVersions|The fixed versions field of an issue|
|comment|Add a comment to an issue|
|time|{note}
To use time attribute, [time tracking|http://confluence.atlassian.com/display/JIRA/Logging+Work+on+an+Issue] must be enabled in your JIRA server. Please check with your JIRA administrator, if you cannot record time tracking information against issues.
{note}
Records the time tracking information of an issue. The syntax for time is:
{code}
<n>w <n>d <n>h <n>m <worklog comment>
{code}
Here, _<n>_ is user specified time period. For example: 1w 2d 3h 20m Total cost period - this will record 1 week 2 days 3 hours and 20 minutes against the issue and add the comment 'Total cost period' in the Work Log tab of the issue.
|
JIRA custom fields are also supported, for custom fields, below format can be used:
{code}
customfield_10000
or just
10000
{code}
here, *10000* is the field id of a custom field. Please reference http://confluence.atlassian.com/display/JIRA/Custom+fields for details about custom field or consult your JIRA administrator for the custom field id.
Below we will give some example commit messages to illustrate the commit commands:
* In below commit message, QuickBuild will resolve the issues TST-1 and TST-2 and add comment _The issue has been fixed_ to both issues.
{code}
1. Modified Foo.java to fix TST-1, TST-2 --comment The issue has been fixed
2. Some dummy comments ...
{code}
* In below commit message, QuickBuild will add _2d 3h_ to the worklog and add comment _Some comment_ to issue TST-1. The value of time _2d 3h_ should be used the format defined in JIRA time tracking.
{code}
Update TST-1 --time 2d 3h --comment Some comment
{code}
* In below commit message, the value of custom field 10000 will be updated to _for custom field1_ and custom field 10001
{code}
Update TST-1 --customfield_10000 for custom field1 --10001 for custom field2
{code}
will be updated to _for custom field2_.
You can define common attributes in the Update Jira Issue step so that when updating issues, the attributes can be applied to all of the issues. When an attribute is specified both in [commit command|Commit Command] and _Extra Attributes_, the value in commit command will be used.
!extra-attributes.png!
h3. Release QuickBuild Version to JIRA
By adding *_Release JIRA Version_* step, QuickBuild can release current build version to primary project defined in configuration settings -> JIRA Server. If this version is not existed, QuickBuild will create it automatically. Also, this step will find all closed or resolved issues in the primary project which were mentioned in commit messages and then update the Fix Version/s field of them.
{note}
* The issues should be in the primary project (first project defined in associated project keys in configuration settings -> JIRA Server
* The user defined in JIRA Setting must have global or project administrator rights in order to release version.
* Only the issues in the primary project will be updated.
{note}
The version can be managed either from QuickBuild or from JIRA:
h4. Manage From QuickBuild
By default, the version is managed by QuickBuild, that means you need not define any version for the associated project in JIRA and QuickBuild will automatically create and release the JIRA version.
h4. Manage From JIRA
Also, you can manage the version from JIRA and use JIRA version as your build version.
{note}
TBD
{note}
h3. Create Issue From QuickBuild
You may create an issue from QuickBuild by adding a *_Create JIRA Issue_* step. A common case is that when build failed, create an issue so that we can track the build from JIRA.
h3. Trouble Shooting
* Q: I can't add comment to a closed issue, why?
A: You need modify the file $JIRA_HOME/atlassian-jira/WEB-INF/classes/jira-workflow.xml, find 'Closed' step and change the value of 'jira.issue.editable' to *true*.
* Q: The commit command failed with error: Workflow step 'Start Progress' is not valid for issue: ABC-123, but I can progress this issue directly from Jira GUI.
A: The user defined in JIRA server should have the permissions to do all of the workflow actions which defined in workflow command transition. If you encountered the problems above, please login to Jira with that user and check the 'Available Workflow Actions' section.