grunt-jira-actions
Grunt tasks to perform Jira actions.
What You Can Do
- Specify Jira connection properties
- Create any type of Jira issue (Epic, Story, Bug, etc)
- Transition issues to any state (Open, In Development, Closed, etc)
- Link two issues together (Blocks, Cloners, Duplicate, Relates)
- Add a comment to an existing issue
- Create a new Version in a Jira project
- Fetch a hash of Jira issues using a JQL search
Requirements
- Grunt
>=0.4.0
- API access to a Jira instance
Installation
I bet you were expecting me to to tell you that if you haven't used Grunt before, to be sure to check out the Getting Started guide, because it explains how to create a Gruntfile as well as install and use Grunt plugins.
Well, I'm not going to do that. Instead, I'm going to assume you are familiar with that process, and will skip ahead to explaining how you can install this plugin. You do so with this command:
npm install grunt-jira-actions --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
Performing Actions in Jira
Specify Jira Connection Properties
The following options are used by all Jira Action tasks:
env_var_for_jira_username
- Environment variable that holds Jira username. Default is 'JIRA_UN'.env_var_for_jira_password
- Environment variable that holds Jira password. Default is 'JIRA_PW'.jira_host
- Base domain of your Jira instance's api root (i.e. 'foo.atlassian.net').jira_protocol
- The protocol which Jira's api uses for connections. Default is 'https'.jira_port
- The port on which Jira's api allows connections on. Default is 443.jira_api_version
- The version of Jira's api to target. Default is '2'.
These values can be set:
- Globaly using the
setJiraConfig
task - In each task's top level options collection (will override global values)
- In each target's option collection (will override task and global values)
Example
module { grunt;}
Creating Jira Issues with 'createJiraIssue'
In your project's Gruntfile, add a section named createJiraIssue
to the data object passed into grunt.initConfig()
. Within that section, you can create any number of targets that add Jira issues of various types. Place common values in the top level options collection. Place target specific values in their respective target's option's collections.
createJiraIssue
targets
Parameters specific to project_id
- Jira id of the project the story will be created in.issue_type
- Jira name of the type of issue to be created. Default is 'Story'. Valid values are:- Bug
- New Feature
- Task
- Improvement
- Sub-task
- Epic
- Story
- Technical Task
issue_state
- The transition id that the issue should end up in. Default is 1 which is Open. 2 is Closed.summary
- Default is the project name specified in package.json (displayed in the story's subject)description
- The description of the issue being created. If value is a valid file path, the contents of the file will be used (plain txt and JSON are supported).optional_fields
- JSON to be added to the create issue call's fields JSON. For more details check developer.atlassian.com
Example
grunt;
Transition an Existing Jira Issue 'transitionJiraIssue'
The transitionJiraIssue
task is called from other tasks, but can also be called directly using the format grunt transitionJiraIssue:<issue_id>:<issue_state>
.
createJiraIssue
targets
Parameters specific to issue_id
- Jira id of the issue that will be transitioned.issue_state
- The transition id that the issue should end up in. Default is 1 which is Open. 2 is Closed.
Example
grunt transitionJiraIssue:19416:2
Add Comments to Existing Issues with 'linkJiraIssues'
The linkJiraIssues
task can be called directly using the format grunt linkJiraIssues:<from_issue_key>:<to_issue_key>:<link_type>:<comment>
.
linkJiraIssues
target
Parameters specific to from_issue_key
- Jira issue KEY that will be linked.to_issue_key
- Jira issue KEY that will be linked.link_type
- The type of link that should be setup. Valid values are 'Blocks', 'Cloners', 'Duplicate', 'Relates'. Default is 'Relates'.comment
- The body of the comment that should accompany the link. If value is a valid file path, the contents of the file will be used (plain txt and JSON are supported).
Example
grunt linkJiraIssues:GEN-200:GEN-201:Relates:tmp/link/description.txt
Add Comments to Existing Issues with 'addJiraComment'
In your project's Gruntfile, add a section named addJiraComment
to the data object passed into grunt.initConfig()
. Within that section, you can create any number of targets that will add Jira comments to existing issues. Place common values in the top level options collection. Place target specific values in their respective target's option's collections.
addJiraComment
target
Parameters specific to issue_id
- Jira id of the project the story will be created in.comment
- The body of the comment being added. If value is a valid file path, the contents of the file will be used (plain txt and JSON are supported).
Example
grunt;
Create a Project Version with 'createJiraVersion'
In your project's Gruntfile, add a section named createJiraVersion
to the data object passed into grunt.initConfig()
. Within that section, you can create any number of targets that can be used to create project versions. Place common values in the top level options collection. Place target specific values in their respective target's option's collections.
createJiraVersion
target
Parameters specific to project
- Jira's three letter project key (ex. 'FOO')name
- String that will be used as the name of the version.description
- The description of the Version being created. If value is a valid file path, the contents of the file will be used (plain txt and JSON are supported).archived
- Boolean value indicating whether the version has been archived. Default is false.released
- Boolean value indicating whether the version has been released. Default is false.release_date
- Date on which the version was released. Default is the current date.
Example
grunt;
Use JQL to fetch a hash of Jira issues with 'searchJira'
In your project's Gruntfile, add a section named searchJira
to the data object passed into grunt.initConfig()
. Within that section, you can create any number of targets that can be used to submit different JQL queries. Place common values in the top level options collection. Place target specific values in their respective target's option's collections.
Each target within this task will save its results grunt.config
with the variable this.target + 'search_results
as a hash of issues with the issue key as the hash key.
searchJira
target
Parameters specific to search_string
- A valid JQL search string.start_at
- Optional page offset for the search. Default is 0.max_results
- Optional max limit of issues. Default is 9999.
Example
grunt;
JQL Search Results
The results hash contains the issue id, key, summary, status id, and status label.
{
'GEN-1':
{ id: '10221',
key: 'GEN-1',
summary: 'Issue summary foo',
status_id: '1',
status: 'Open' },
'GEN-2':
{ id: '13897',
key: 'GEN-2',
summary: 'Issue summary bar',
status_id: '1',
status: 'Open' },
'GEN-3':
{ id: '17429',
key: 'GEN-3',
summary: 'Issue summary baz',
status_id: '1',
status: 'Open' }
}
Experimental : jiraProjectRapidView
grunt;
Contact, feedback and bugs
This interface was not developed or reviewed by Atlassian. They bare no responsibility for its quality, performance, or results. Use at your own risk.
Please file bugs / issues and feature requests on the issue tracker
Contributing
The code styleguide for this project is captured in the eslint.json file. Submissions should be accompanied by unit tests for any new or changed functionality. esLint and test your code using Grunt.
Special Thanks
- Ryan Tomlinson for the helpful write up of OpenTable's release process
- OpenTable - for being a progressive organization and allowing their staff to open source their tools.
- Chris Riddle and Bryce Catlin for putting together grunt-ccb, which this project is derived from.