This documentation relates to QuickBuild 11.0.x
Select here if you are using a different version

Integrating QuickBuild with JIRA

Version 3 by Steve Luo
on Dec 27, 2021 10:37.

<< Changes from 2 to 3
compared with
Current by Steve Luo
on Dec 27, 2021 11:00.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 2 changes. View first change.

 Since 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=4}
  
 {info}
 Supported JIRA version should be JIRA 3.13.3 or higher.
 {info}
  
 h3. Basic 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 a JIRA project with this configuration. This project is used when you want to update issues or release version to JIRA. See details 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!
  
 *NOTE* The issues here will synchronize with JIRA to reflect their latest status.
  
 you can also find all related issues from a specified version and view their changes:
 !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. Advanced Integration
 Besides the basic integration, QuickBuild also features:
 * Update issues mentioned in commit messages directly
 * Cooperate with JIRA to manage both JIRA and QuickBuild version
 * Release a JIRA version and also update the Fix Version/s field of issues mentioned in commit messages which can help you to generate the Release Notes easily.
  
 h4. Update Issues
 To update issues from the commit messages, *Update JIRA Issue* step should be added to your build workflow. And you need specify one or more issue updater(s) below in the step:
 * Update issues according to SCM commit messages
 * Update issues by a specified JIRA filter
 * Update issues with specified issue keys
 * Update issues corresponding to changeset closed tasks
  
 By default, QuickBuild will update issues according to SCM commit messages.
  
 h5. Update issues according to SCM commit messages
  
 When QuickBuild find any [commit commands|Commit Command] in the commit message, it will execute these commands to update or progress the issues listed in the commands.
  
 *NOTE:*
  * 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 associated project be updated.
  
 h5. Customize Commit Command
  
 The [commit command|Commit Command] has two types:
 * Progress Command which is used to progress an issue in the JIRA workflow and *step* attribute is required.
 * Update Command which is used to update an issue only and will not lead to a workflow transition.
  
 The commit commands can be customized in the Update Jira Issue step based on your JIRA workflow definition.
  
 !commit-commands.png!
  
 h5. Command Attributes
  
 A [commit command|Commit Command] has below attributes, each attribute relates to the field of an issue:
  
 ||Attribute||Description||
 |summary|a brief one-line summary of the issue.|
 |description|a detailed description of the issue.|
 |type|the type of the issue, for example: Bug, Improvement, Task, etc.|
 |priority|the importance of the issue in relation to other issues.|
 |resolution|a record of the issue's resolution, if the issue has been resolved or closed.|
 |step|the workflow transition that this command triggers. For example, step=Start Progress will progress issue to 'In Progress' status. See [JIRA workflow|http://confluence.atlassian.com/pages/viewpage.action?pageId=185729618] for details.|
 |reporter|the person who entered the issue into the system.|
 |assignee|the person to whom the issue is currently assigned.|
 |duedate|specify the issue due date.|
 |dateFormat|specify the date format for due date.|
 |environment|the hardware or software environment to which the issue relates.|
 |affectsVersions|project version(s) for which the issue is (or was) manifesting.|
 |fixVersions|project version(s) in which the issue was (or will be) fixed.|
 |comment|the comment which will be added to the issue and will be diplayed in issue comment tab.|
 |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=Hello, Custom Field
 or
 customfield_My Custom Field Name=Hello, Custom Field
 {code}
 here, *10000* is the field id of a custom field, and 'My Custom Field Name' is the name of the 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 field_
 {code}
 Update TST-1 --customfield_10000 for custom field
 {code}
  
  
 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!
  
 h5. Update issues by a specified JIRA filter
 This updater is used to retrieve the issues to be updated from a specified JIRA filter. This filter should be saved by the user defined in configuration JIRA server setting. And you also need specify the workflow action you want to take.
 !filter-updater!
  
 h5. Update issues with specified issue keys
 This updater is much similar to update issues by filter. You can specify the JIRA keys directly here, or you can input a script here to generate the issue keys to be updated.
  
 h5. Update issues corresponding to changeset closed tasks
 Currently, this updater can only work with Perforce. If your Perforce job is associated with JIRA issue, QuickBuild will extract the issue keys from those closed jobs and then update the issue status.
  
 h4. Release QuickBuild Version to JIRA
 To release version to JIRA, *_Release JIRA Version_* step should be added to your build workflow. And this step will release the build version to the associated project in JIRA. If this version does not exist, QuickBuild will create it automatically. Also, you can define one or more issue provider(s) below to provide the issues which you want to update their 'Fix Version/s' fields:
 * Resolved/Closed issues found in commit messages
 * Resolved/Closed issues in previous update issue steps
 * Issues filtered by a specified filter (the filter should be saved by the user defined in configuration JIRA server setting)
 * Issues with specified keys
 * Issues corresponding to changeset closed tasks (currently, this can only work with Perforce, see Update issues corresponding to changeset closed tasks above)
 * Do not update issues
  
 h5. Resolved/Closed issues found in commit messages
  
 h5. Resolved/Closed issues in previous update issue steps
  
 h5. Issues filtered by a specified filter
 The filter should be saved by the user defined in configuration JIRA server setting.
  
 h5. Issues with specified keys
 You can specify the issue keys directly or you can input a script to generate the issue keys.
  
 h5. Issues corresponding to changeset closed tasks
 Currently, this can only work with Perforce. If your Perforce job is associated with JIRA issue, QuickBuild will extract the issue keys from those closed jobs.
  
 h5. Do not update issues
 If you don't want to update the Fix Version/s field, you can use this.
  
 {note}
 * The user defined in JIRA Setting must have global or project administrator rights in order to release version.
 * Only the issues with status closed or resolved in the associated project will be updated.
 {note}
  
 The version can be managed either from QuickBuild or from JIRA:
  
 h5. 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 version of this build.
  
 h5. Manage from JIRA
 Sometimes, you want to manage the versions in JIRA side by yourself and let QuickBuild retrieve the version from JIRA. In this scenario, you just need change your _Next Build Version_ (in configuration settings -> General Setting section) to _use next unreleased version from JIRA_, and then you will find the next build version will be the first unreleased version you defined in JIRA when go to configuration dashboard.
 !nextversion.png!
  
  
 h4. 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 have written the commit commands in my commit message correctly, but QuickBuild doesn't execute them and update the issues.*
  A: In most cases, that is because your SCM user does not associate with your JIRA account correctly. See [how to associate them|#associate_users] in this page.
 * *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.*
  A: Normally, this is caused by several commit commands were submitted in wrong order to change the issue status. For example, two commit commands submitted to progress issue TST-123:
 1. Close TST-123 // OK, changed status to Closed
 2. Fix TST-123 // Error! Workflow step is not valid
  
 * *Q: How to update a custom field with multiple users selection*
  A: To update a custom field with multiple users, you can input below lines in the Extra Attributes field:
  customfield_Your Users Field=name:steve,name:robin
  That is, use comma to separate the user and use colon to separate the property.
  
  
 h2. Triggering Build via Webhook
  
 To trigger build via JIRA webhook, first, you need create a webhook setting in JIRA like below:
  
 !jira-webhook-setting.png!
  
 Here, the URL is in below format:
  
 {code}
 http://quickbuild.host/rest/webhook/jira/${project.key}?token={your_token}
 {code}
  
 Please replace the QuickBuild host and token with your actual value.
  
 The token is used for verification with QuickBuild.
  
 After setting up at JIRA side, go back to QuickBuild, in Administration -> Plugin Management page, search JIRA plugin:
  
 !quickbuild-jira-webhook-plugin.png!
  
 then config it by filling below two fields:
  
 * Project Mappings, config the project mappings between JIRA project and QuickBuild configuration.
 * Token, specify the access token for security reason
  
 then, go to the configuration you want and set up the webhook setting in the configuration setting:
  
 !configuration-jira-webhook.png!
  
 filling below fields:
  
 !quickbuild-jira-webhook-settings.png!