Hubot Jira Bot

Lets you search for JIRA tickets, open them, transition them thru different states, comment on them, rank them up or down, start or stop watching them or change who is assigned to a ticket. Also, notifications for assignments, mentions and watched tickets.

Dependencies:

• moment
• octokat
• node-fetch
• underscore
• fuse.js

Configuration:

• HUBOT_GITHUB_ORG - Github Organization or Github User
• HUBOT_GITHUB_TOKEN - Github Application Token
• HUBOT_JIRA_GITHUB_DISABLED - Set to true if you wish to disable github integration
• HUBOT_JIRA_MENTIONS_DISABLED - Set to true if you wish to disable posting tickets in response to mentions in normal messages
• HUBOT_JIRA_PASSWORD
• HUBOT_JIRA_PRIORITIES_MAP [{"name":"Blocker","id":"1"},{"name":"Critical","id":"2"},{"name":"Major","id":"3"},{"name":"Minor","id":"4"},{"name":"Trivial","id":"5"}]
• HUBOT_JIRA_PROJECTS_MAP {"web":"WEB","android":"AN","ios":"IOS","platform":"PLAT"}
• HUBOT_JIRA_TRANSITIONS_MAP [{"name":"triage","jira":"Triage"},{"name":"icebox","jira":"Icebox"},{"name":"backlog","jira":"Backlog"},{"name":"devready","jira":"Selected for Development"},{"name":"inprogress","jira":"In Progress"},{"name":"design","jira":"Design Triage"}]
• HUBOT_JIRA_TYPES_MAP {"story":"Story / Feature","bug":"Bug","task":"Task"}
• HUBOT_JIRA_URL https://jira-domain.com:9090
• HUBOT_JIRA_USERNAME
• HUBOT_JIRA_FIELDS customize the jira fields returned by api, defaults to: ["issuetype", "status", "assignee", "reporter", "summary", "description", "labels", "project"]
• HUBOT_SLACK_BUTTONS {"watch":{"name":"watch","text":"Watch","type":"button","value":"watch","style":"primary"},"assign":{"name":"assign","text":"Assign to me","type":"button","value":"assign"},"devready":{"name":"devready","text":"Dev Ready","type":"button","value":"selected"},"inprogress":{"name":"inprogress","text":"In Progress","type":"button","value":"progress"},"rank":{"name":"rank","text":"Rank Top","type":"button","value":"top"},"running":{"name":"running","text":"Running","type":"button","value":"running"},"review":{"name":"review","text":"Review","type":"button","value":"review"},"resolved":{"name":"resolved","text":"Resolved","type":"button","style":"primary","value":"resolved"},"done":{"name":"done","text":"Done","type":"button","style":"primary","value":"done"}}
• HUBOT_SLACK_PROJECT_BUTTON_STATE_MAP {"PLAT":{"inprogress":["review","running","resolved"],"review":["running","resolved"],"running":["resolved"],"resolved":["devready","inprogress"],"mention":["watch","assign","devready","inprogress","rank"]},"HAL":{"inprogress":["review","running","resolved"],"review":["running","resolved"],"running":["resolved"],"resolved":["devready","inprogress"],"mention":["watch","assign","devready","inprogress","rank"]},"default":{"inprogress":["review","done"],"review":["done"],"done":["devready, inprogress"],"mention":["watch","assign","devready","inprogress","rank"]}}
• HUBOT_SLACK_VERIFICATION_TOKEN - The slack verification token for your application

Note that HUBOT_JIRA_USERNAME should be the JIRA username, this is not necessarily the username used if you log in via the web. To determine a user's username, log in as that user via the web, and check the user profile. Frequently, users may log in using an email address such as '[e-mail]' or a stem, such as 'bob'; these may or may not match the username in JIRA.

A note about chat:jira user lookup

In order for direct messages (notifications) and a few other username based commands to work JiraBot attempts to match JIRA users with chat users by email address. This has been tested primarily on the Hubot Slack adapter and may not work without modification on others. The take away is that you must have the same e-mail address on both services for this to work as expected.

Notifications via Webhooks

In order to receive JIRA notifications you will need to setup a webhook. You can find instructions to do so on Atlassian's website. You will need your hubot to be reachable from the outside world for this to work. JiraBot is listening on /hubot/jira-events. Currently the following notifications are available:

• You are mentioned in a ticket in either the description or in a comment
• You are assigned to a ticket
• The following notifications apply if you are assigned to the ticket:
  • A new comment is left on the ticket
• The following notifications apply if you are watching the ticket in question:
  • Work begins on the ticket (enters the In Progress state or similar)
  • The ticket is closed
  • A new comment is left on the ticket

The Definitive hubot JIRA Manual

@hubot can help you search for JIRA tickets, open them, transition them thru different states, comment on them, rank them up or down, start or stop watching them or change who is assigned to a ticket

Opening Tickets

hubot [<project>] <type> <title> [<description>]

You can omit <project> when using the command in the desired projects channel Otherwise you can specify one of the following for <project>: # web, # android, # ios, # platform <type> is one of the following: story, bug, task <description> is optional and is surrounded with single or triple backticks and can be used to provide a more detailed description for the ticket. <title> is a short summary of the ticket

Optional <title> Attributes

Labels: include one or many hashtags that will become labels on the jira ticket # quick # techdebt

Assignment: include a handle that will be used to assign the ticket after creation @username

Transitions: include a transition to make after the ticket is created >triage, >icebox, >backlog, >devready, >inprogress, >design

Priority: include the ticket priority to be assigned upon ticket creation !blocker, !critical, !major, !minor, !trivial

Creating Sub-tasks

hubot subtask <ticket> <summary>

Where <ticket> is the parent JIRA ticket number and <summary> is a short summary of the task

Cloning Tickets

<ticket> clone to <channel> <ticket> > <channel>

Where <ticket> is the JIRA ticket number and <channel> is one of the following: # web, # android, # ios, # platform

Ranking Tickets

<ticket> rank top <ticket> rank bottom

Where <ticket> is the JIRA ticket number. Note this will rank it the top of column for the current state

Commenting on a Ticket

<ticket> < <comment>

Where <ticket> is the JIRA ticket number and <comment> is the comment you wish to leave on the ticket

Adding labels to a Ticket

<ticket> < # label1 # label2 # label3

Where <ticket> is the JIRA ticket number

Assigning Tickets

<ticket> assign @username

Where <ticket> is the JIRA ticket number and @username is a user handle

Transitioning Tickets

<ticket> to <state> <ticket> ><state>

Where <ticket> is the JIRA ticket number and <state> is one of the following: triage, icebox, backlog, devready, inprogress, design

Watching Tickets

<ticket> watch [@username]]

Where <ticket> is the JIRA ticket number @username is optional, if specified the corresponding JIRA user will become the watcher on the ticket, if omitted the message author will become the watcher

Ticket Notifications

Whenever you begin watching a JIRA ticket you will be notified (via a direct message from @hubot) whenever any of the following events occur: - a comment is left on the ticket - the ticket is in progress - the ticket is resolved

You will also be notified if: - you are mentioned on the ticket - you are assigned to the ticket

If you are assigned to a ticket, you will be notified when: - a comment is left on the ticket

To enable or disable this feature you can send the following directly to hubot:

jira disable notifications

or if you wish to re-enable

jira enable notifications

Searching Tickets

hubot jira search <term>

Optional <term> Attributes

Labels: include one or many hashtags that will become labels included in the search # quick # techdebt

Where <term> is some text contained in the ticket you are looking for## Documentation with Configuration examples from above

Quering Tickets with JQL

hubot jira query <jql>

Where <jql> is a valid JQL query """