1 | # Hubot Jira Bot
|
2 | Lets you search for JIRA tickets, open
|
3 | them, transition them thru different states, comment on them, rank
|
4 | them up or down, start or stop watching them or change who is
|
5 | assigned to a ticket. Also, notifications for assignments, mentions and watched tickets.
|
6 |
|
7 | ###Dependencies:
|
8 | - moment
|
9 | - octokat
|
10 | - node-fetch
|
11 | - underscore
|
12 | - fuse.js
|
13 |
|
14 | ###Configuration:
|
15 | - `HUBOT_GITHUB_ORG` - Github Organization or Github User
|
16 | - `HUBOT_GITHUB_TOKEN` - Github Application Token
|
17 | - `HUBOT_JIRA_GITHUB_DISABLED` - Set to true if you wish to disable github integration
|
18 | - `HUBOT_JIRA_PASSWORD`
|
19 | - `HUBOT_JIRA_PRIORITIES_MAP` `[{"name":"Blocker","id":"1"},{"name":"Critical","id":"2"},{"name":"Major","id":"3"},{"name":"Minor","id":"4"},{"name":"Trivial","id":"5"}]`
|
20 | - `HUBOT_JIRA_PROJECTS_MAP` `{"web":"WEB","android":"AN","ios":"IOS","platform":"PLAT"}`
|
21 | - `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"}]`
|
22 | - `HUBOT_JIRA_TYPES_MAP` `{"story":"Story / Feature","bug":"Bug","task":"Task"}`
|
23 | - `HUBOT_JIRA_URL` `https://jira-domain.com:9090`
|
24 | - `HUBOT_JIRA_USERNAME`
|
25 | - `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"}}`
|
26 | - `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"]}}`
|
27 | - `HUBOT_SLACK_VERIFICATION_TOKEN` - The slack verification token for your application
|
28 |
|
29 | Note that `HUBOT_JIRA_USERNAME` should be the JIRA username, this is
|
30 | not necessarily the username used if you log in via the web. To
|
31 | determine a user's username, log in as that user via the web, and check
|
32 | the user profile. Frequently, users may log in using an email address such
|
33 | as 'bob@somewhere.com' or a stem, such as 'bob'; these may or may not match
|
34 | the username in JIRA.
|
35 |
|
36 | ####A note about chat:jira user lookup
|
37 | In order for direct messages (notifications) and a few other
|
38 | username based commands to work JiraBot attempts to match JIRA users with chat
|
39 | users by email address. This has been tested primarily on the [Hubot
|
40 | Slack adapter](https://github.com/slackhq/hubot-slack) and may not work without modification on others.
|
41 | The take away is that you must have the same e-mail address on both
|
42 | services for this to work as expected.
|
43 |
|
44 | ####Notifications via Webhooks
|
45 | In order to receive JIRA notifications you will need to setup a webhook.
|
46 | You can find instructions to do so on [Atlassian's
|
47 | website](https://developer.atlassian.com/jiradev/jira-apis/webhooks).
|
48 | You will need your hubot to be reachable from the outside world for this
|
49 | to work. JiraBot is listening on `/hubot/jira-events`. Currently
|
50 | the following notifications are available:
|
51 |
|
52 | * You are mentioned in a ticket in either the description or in a
|
53 | comment
|
54 | * You are assigned to a ticket
|
55 | * The following notifications apply if you are assigned to the ticket:
|
56 | * A new comment is left on the ticket
|
57 | * The following notifications apply if you are watching the ticket in
|
58 | question:
|
59 | * Work begins on the ticket (enters the In Progress state or similar)
|
60 | * The ticket is closed
|
61 | * A new comment is left on the ticket
|
62 |
|
63 | ###The Definitive hubot JIRA Manual
|
64 | @hubot can help you *search* for JIRA tickets, *open*
|
65 | them, *transition* them thru different states, *comment* on them, *rank*
|
66 | them _up_ or _down_, start or stop *watching* them or change who is
|
67 | *assigned* to a ticket
|
68 |
|
69 |
|
70 | ####Opening Tickets
|
71 | > hubot [`<project>`] `<type>` `<title>` [`<description>`]
|
72 |
|
73 | You can omit `<project>` when using the command in the desired projects channel
|
74 | Otherwise you can specify one of the following for `<project>`: `#web`, `#android`, `#ios`, `#platform`
|
75 | `<type>` is one of the following: `story`, `bug`, `task`
|
76 | `<description>` is optional and is surrounded with single or triple backticks
|
77 | and can be used to provide a more detailed description for the ticket.
|
78 | `<title>` is a short summary of the ticket
|
79 |
|
80 | #####Optional `<title>` Attributes
|
81 |
|
82 | _Labels_: include one or many hashtags that will become labels on the jira ticket
|
83 | `#quick #techdebt`
|
84 |
|
85 | _Assignment_: include a handle that will be used to assign the ticket after creation
|
86 | `@username`
|
87 |
|
88 | _Transitions_: include a transition to make after the ticket is created
|
89 | `>triage`, `>icebox`, `>backlog`, `>devready`, `>inprogress`, `>design`
|
90 |
|
91 | _Priority_: include the ticket priority to be assigned upon ticket creation
|
92 | `!blocker`, `!critical`, `!major`, `!minor`, `!trivial`
|
93 |
|
94 |
|
95 | ####Creating Sub-tasks
|
96 | > hubot subtask `<ticket>` `<summary>`
|
97 |
|
98 | Where `<ticket>` is the parent JIRA ticket number
|
99 | and `<summary>` is a short summary of the task
|
100 |
|
101 |
|
102 | ####Cloning Tickets
|
103 | >`<ticket>` clone to `<channel>`
|
104 | > `<ticket>` > `<channel>`
|
105 |
|
106 | Where `<ticket>` is the JIRA ticket number
|
107 | and `<channel>` is one of the following: `#web`, `#android`, `#ios`, `#platform`
|
108 |
|
109 |
|
110 | ####Ranking Tickets
|
111 | >`<ticket>` rank top
|
112 | > `<ticket>` rank bottom
|
113 |
|
114 | Where `<ticket>` is the JIRA ticket number. Note this will rank it the top
|
115 | of column for the current state
|
116 |
|
117 |
|
118 | ####Commenting on a Ticket
|
119 | >`<ticket>` < `<comment>`
|
120 |
|
121 | Where `<ticket>` is the JIRA ticket number
|
122 | and `<comment>` is the comment you wish to leave on the ticket
|
123 |
|
124 |
|
125 | ####Adding labels to a Ticket
|
126 | >`<ticket>` < `#label1 #label2 #label3`
|
127 |
|
128 | Where `<ticket>` is the JIRA ticket number
|
129 |
|
130 |
|
131 | ####Assigning Tickets
|
132 | >`<ticket>` assign `@username`
|
133 |
|
134 | Where `<ticket>` is the JIRA ticket number
|
135 | and `@username` is a user handle
|
136 |
|
137 |
|
138 | ####Transitioning Tickets
|
139 | >`<ticket>` to `<state>`
|
140 | > `<ticket>` >`<state>`
|
141 |
|
142 | Where `<ticket>` is the JIRA ticket number
|
143 | and `<state>` is one of the following: `triage`, `icebox`, `backlog`, `devready`, `inprogress`, `design`
|
144 |
|
145 |
|
146 | ####Watching Tickets
|
147 | >`<ticket>` watch [`@username]`]
|
148 |
|
149 | Where `<ticket>` is the JIRA ticket number
|
150 | `@username` is optional, if specified the corresponding JIRA user will become
|
151 | the watcher on the ticket, if omitted the message author will become the watcher
|
152 |
|
153 |
|
154 | ####Ticket Notifications
|
155 |
|
156 | Whenever you begin watching a JIRA ticket you will be notified (via a direct
|
157 | message from @hubot) whenever any of the following events occur:
|
158 | - a comment is left on the ticket
|
159 | - the ticket is in progress
|
160 | - the ticket is resolved
|
161 |
|
162 | You will also be notified if:
|
163 | - you are mentioned on the ticket
|
164 | - you are assigned to the ticket
|
165 |
|
166 | If you are assigned to a ticket, you will be notified when:
|
167 | - a comment is left on the ticket
|
168 |
|
169 | To enable or disable this feature you can send the following directly to hubot:
|
170 |
|
171 | > jira disable notifications
|
172 |
|
173 | or if you wish to re-enable
|
174 |
|
175 | > jira enable notifications
|
176 |
|
177 |
|
178 | ####Searching Tickets
|
179 | > hubot jira search `<term>`
|
180 |
|
181 | #####Optional `<term>` Attributes
|
182 | _Labels_: include one or many hashtags that will become labels included in the search
|
183 | `#quick #techdebt`
|
184 |
|
185 | Where `<term>` is some text contained in the ticket you are looking for##Documentation with Configuration examples from above
|