1 | Hubot Phabricator Plugin
|
2 | =================================
|
3 |
|
4 | [![Version](https://img.shields.io/npm/v/hubot-phabs.svg)](https://www.npmjs.com/package/hubot-phabs)
|
5 | [![Downloads](https://img.shields.io/npm/dt/hubot-phabs.svg)](https://www.npmjs.com/package/hubot-phabs)
|
6 | [![Build Status](https://img.shields.io/travis/Gandi/hubot-phabs.svg)](https://travis-ci.org/Gandi/hubot-phabs)
|
7 | [![Dependency Status](https://gemnasium.com/Gandi/hubot-phabs.svg)](https://gemnasium.com/Gandi/hubot-phabs)
|
8 | [![Coverage Status](http://img.shields.io/codeclimate/coverage/github/Gandi/hubot-phabs.svg)](https://codeclimate.com/github/Gandi/hubot-phabs/coverage)
|
9 | [![NPM](https://nodei.co/npm/hubot-phabs.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/hubot-phabs/)
|
10 |
|
11 | This plugin is designed to work as an addon for [Hubot](https://hubot.github.com/). Its role is to make interactions possible between a chat room (irc, slack, gitter) and a [phabricator](https://www.phacility.com/phabricator/) instance.
|
12 |
|
13 | When installed this plugin will check the channels where the bot lurks, to see if someone is talking about Phabricator objects (T32 or P156 or F1526) to complement the conversation with the name of the referred item.
|
14 |
|
15 | It also makes available some commands to interact directly with Phabricator items, like create a task, assign a task to a user. This is a work in progress and more commands will be added with time.
|
16 |
|
17 | This plugin is used in production internally at [Gandi](https://gandi.net) since 2016-07-13.
|
18 |
|
19 | Check the [Changelog](CHANGELOG.md) for a precise history of the versions.
|
20 |
|
21 | > TOC
|
22 | > --------------
|
23 | >
|
24 | > - [Installation](#installation)
|
25 | > - [Permission System](#permission-system)
|
26 | > - [Configuration](#configuration)
|
27 | > - [Features](#features)
|
28 | > - [events](#events-feature)
|
29 | > - [api](#api-feature)
|
30 | > - [commands](#commands-feature)
|
31 | > - [templates](#templates-feature)
|
32 | > - [admin](#admin-feature)
|
33 | > - [feeds](#feeds-feature)
|
34 | > - [hear](#hear-feature)
|
35 | > - [Development](#development)
|
36 | > - [Changelog](#changelog)
|
37 | > - [Testing](#testing)
|
38 | > - [Contribute](#contribute)
|
39 | > - [Attribution](#attribution)
|
40 | > - [Authors](#authors)
|
41 | > - [License](#license)
|
42 | > - [Copyright](#copyright)
|
43 |
|
44 | Installation
|
45 | --------------
|
46 | In your hubot directory:
|
47 |
|
48 | npm install hubot-phabs --save
|
49 |
|
50 | Then add `hubot-phabs` to `external-scripts.json`
|
51 |
|
52 | Next you need to create a `bot` user in Phabricator and grab its api key.
|
53 |
|
54 |
|
55 | Permission system
|
56 | -------------------
|
57 |
|
58 | By default every action is usable by any user. But you can follow the optional permission system by using the `hubot-auth` module.
|
59 |
|
60 | There are mainly 3 permissions groups:
|
61 |
|
62 | - `admin` group, for which everything is permitted everywhere
|
63 | - `phadmin` group, required for which everything is permitted on `.phab` and `.phad` commands
|
64 | - `phuser` group, which cannot use
|
65 | - the `.phad` command except `.phad projects`
|
66 | - the `.phab user = email` command
|
67 | - the 'not in any group' user, which cannot
|
68 | - create new task
|
69 | - create new paste
|
70 | - change status or permission
|
71 | - assign a task to someone
|
72 | - set an email or check other users
|
73 |
|
74 | If you set the variable `PHABRICATOR_TRUSTED_USERS` to `y`, then the 'not in any group' users can access all the features reserved for the `phuser` group. Typically the `phuser` role is designed to be used on public irc or gitter channels, but is not needed in closed slack channels.
|
75 |
|
76 | Configuration
|
77 | -----------------
|
78 |
|
79 | - `PHABRICATOR_URL` - main url of your Phabricator instance
|
80 | - `PHABRICATOR_API_KEY` - api key for the bot user
|
81 | - `PHABRICATOR_LAST_TASK_LIFETIME` - how long the last task is remembered for each user (default 60 min)
|
82 |
|
83 | If you use `hubot-auth`
|
84 | - `HUBOT_AUTH_ADMIN` - hardcoded list of hubot admins
|
85 | - `PHABRICATOR_TRUSTED_USERS` - if set to 'y', bypasses the requirement of belonging to `phuser` group for commands restricted to users. Makes sense in places where all users are internal or invited-only and trustworthy.
|
86 |
|
87 | You also should use `hubot-restrict-ip` to limit the access to the web endpoints (api and feeds endpoints), or serve only on localhost (`EXPRESS_BIND_ADDRESS=127.0.0.1`) and use a proxy to access those endpoints.
|
88 |
|
89 | - `PHABRICATOR_ENABLED_ITEMS` - is used with feature `hear` to limit what kind of objects are commonly used in your instance of Phabricator
|
90 |
|
91 |
|
92 |
|
93 | Features
|
94 | ----------------
|
95 |
|
96 | The `hubot-phabs` plugin has a lot of features, and some of them could be useless, or dangerous if activated under an unprotected environment. There are 2 environment variables that can be used to limit what features are loaded and active:
|
97 |
|
98 | - `PHABS_ENABLED_FEATURES` can be a comma-separated list of the only plugins enabled.
|
99 | - `PHABS_DISABLED_FEATURES` is also a comma-separated list of features, to only restrict a few ones. It won't be any use if the `PHABS_ENABLED_FEATURES` is declared, as it would take priority.
|
100 |
|
101 | Typical examples of usage are:
|
102 |
|
103 | - `PHABS_ENABLED_FEATURES="hear"` if you only want the bot to do automatic announces
|
104 | - `PHABS_DISABLED_FEATURES="feeds,api"` if you don't want to expose http endpoints
|
105 | - `PHABS_DISABLED_FEATURES="admin,feeds"` if you don't use `hubot-auth`. Note that you can do the setup with the admin feature at first, and then just disable it (and relaunch the bot in between).
|
106 |
|
107 | Available features are loaded in that order:
|
108 |
|
109 | - `events`
|
110 | - `api`
|
111 | - `commands`
|
112 | - `templates`
|
113 | - `admin`
|
114 | - `feeds`
|
115 | - `hear`
|
116 |
|
117 |
|
118 | ### Events feature
|
119 |
|
120 | There is some events available for interaction with other plugins, to chain actions or automate them. The specific use case we had was to use [hubot-cron-events](https://github.com/Gandi/hubot-cron-events) to create templated tasks are given times. It is making sense in our workflow. The principle is pretty useful, so there will be more events declared further on.
|
121 |
|
122 | phab.createTask
|
123 | payload:
|
124 | - project (by name or alias)
|
125 | - template (null if none)
|
126 | - title
|
127 | - description
|
128 | - user (an object with at least a name property)
|
129 | - assign (as a user name)
|
130 | - announce (optional: the name of a room where to announce the task creation and id)
|
131 | It will create a task from an event,
|
132 | and talk on the logger when done or if it fails.
|
133 |
|
134 | ### API feature
|
135 |
|
136 | It may seem a little weird, but circumstances led us to use our hubot as an API endpoint for creating tasks from inside our internal network. Of course we could just use conduit and hit Phabricator directly but:
|
137 |
|
138 | - we save the hassle of spreading the API key around
|
139 | - we are inside a trusted network, and use hubot-restrict-ip
|
140 | - we expose REST endpoints, with only very simplified payload description
|
141 |
|
142 | To avoid exposure of that weak API endpoint, you should:
|
143 |
|
144 | - set the env var PHABS_NO_API to any value, if it's defined, the api code is not loaded
|
145 | - use [hubot-restrict-ip](https://github.com/Gandi/hubot-restrict-ip) to set up your own policy
|
146 | - set your hubot to respond http calls through a well configured apache or nginx proxy
|
147 |
|
148 | Currently the API only has one endpoint, that triggers the `phab.createTask` event
|
149 |
|
150 | POST /<robot.name>/phabs/api/:project/task
|
151 | where :project can be a project name or an alias
|
152 | that you have set with .phad
|
153 | the content-type has to be application/json
|
154 | and the payload should conform to the payload
|
155 | for the phab.createTask event
|
156 |
|
157 | ### Commands feature
|
158 |
|
159 | Commands prefixed by `.phab` are here taking in account we use the `.` as hubot prefix, just replace it with your prefix if it is different. Also, `phab` can be shortened to `ph` in the commands.
|
160 |
|
161 | Requests can be done on arbitrary projects. Their PHID will be retrieved at first call and cached in hubot brain. Those projects can use aliases, like short names, interchangeably, for convenience (set them up using the `.phad` command).
|
162 |
|
163 | .phab <project> search terms
|
164 | will grab the 3 newest matches in tasks matching search terms.
|
165 | note that there are some special rules:
|
166 | - non-alphanumeric chars will be mess up
|
167 | - the match is done on full-words: test won't match tests
|
168 | permission: all
|
169 |
|
170 | .phab new <project> <task title>
|
171 | .phab new <project> <task title> = <description>
|
172 | creates a new task in an arbitrary project.
|
173 | A project alias can also be used.
|
174 | The new task will be created in the default column of the project board.
|
175 | The issuer of the command will be added in the list of subscribers
|
176 | for the newly created task.
|
177 | The <description> is optional, and will be used as description if provided
|
178 | NOTE: this call will record this Task id associated to you for 5 minutes
|
179 | permission: phuser
|
180 |
|
181 | .phab new <project>:<template> <task title>
|
182 | .phab new <project>:<template> <task title> = <description>
|
183 | creates a new task using a template.
|
184 | if a description is provided, it will prepend the template description
|
185 | For the rest, it behaves like the .phab new command
|
186 | permission: phuser
|
187 |
|
188 | .phab paste <new paste title>
|
189 | creates a new paste and provide the link to edit it
|
190 | permission: phuser
|
191 |
|
192 | .phab T123
|
193 | .phab
|
194 | gives the status, priority and owner of the task xxx
|
195 | NOTE: this call will record this Task id associated to you for 5 minutes
|
196 | permission: all
|
197 |
|
198 | .phab T123 + <some comment>
|
199 | .phab + <some comment>
|
200 | adds a comment to task Txxx (or the one in short memory).
|
201 | permission: phuser
|
202 |
|
203 | .phab T123 in tag1
|
204 | .phab T123 not in tag1
|
205 | .phab T123 in tag1 in tag2 not in tag3 in tag4
|
206 | adds or remove tags from tasks. Tags are also known as projects
|
207 | permission: phuser
|
208 |
|
209 | .phab T123 is open
|
210 | .phab T123 is broken
|
211 | .phab is low
|
212 | .phab low
|
213 | .phab is low = this is a reason
|
214 | .phab is low + this is a reason
|
215 | Changes status or priority for task Txxx. the 'is' is optional.
|
216 | If the optional '=' or '+' is used, it will add a comment to that change
|
217 | Available statuses are:
|
218 | - open, opened -> open
|
219 | - resolved, resolve, closed, close -> resolved
|
220 | - wontfix, noway -> wontfix
|
221 | - invalid, rejected -> invalid
|
222 | - spite, lame -> spite
|
223 | Available priorities are
|
224 | - broken, unbreak -> Unbreak Now!
|
225 | - none, unknown, triage -> Needs Triage
|
226 | - high, urgent -> High
|
227 | - normal -> Normal
|
228 | - low -> Low
|
229 | - wish, wishlist -> Whishlist
|
230 | NOTE: this call will record this Task id associated to you for 5 minutes
|
231 | permission: phuser
|
232 |
|
233 | .phab T123 on <someone>
|
234 | .phab for <someone>
|
235 | assigns the given task to a user (or the given user to the task,
|
236 | which is exactly the same).
|
237 | The 'for' and 'on' conjunctions are inter-changeable.
|
238 | NOTE: this call will record this Task id associated to you for 5 minutes
|
239 | permission: phuser
|
240 |
|
241 | .phab T123 to <column>
|
242 | .phad to <column>
|
243 | .phad T123 to <column> + some comment
|
244 | .phad T123 to <column> = some comment
|
245 | moves the task on the board to the column matching the <column>
|
246 | the matching will take the first match.
|
247 | A comment can optionaly be added
|
248 | permission: phuser
|
249 |
|
250 | .phab T123 on <someone> is low is open to <column>
|
251 | starting with `v2.2.0` it's possible to combine several commands to
|
252 | change a task. It detects actions to be taken according to the conjonction used:
|
253 | - on - change owner
|
254 | - for - change owner (alias to on)
|
255 | - is - change status or priority
|
256 | - in - change tag/project (add a tag)
|
257 | - not in - change tag/project (remove a tag)
|
258 | - to - change column
|
259 | permission: phuser
|
260 |
|
261 | .phab T123 next <term>
|
262 | .phab T123 next
|
263 | .phab next
|
264 | This will return the first match in the Task T123 description
|
265 | that begins with a [ ] (a checkbox)
|
266 | if a <term> is provided, it will match the first line
|
267 | that begins with '[ ] term'
|
268 | the first word on the line, just after the checkbox, is used
|
269 | as a keyword, but it's totally optional
|
270 | permission: phuser
|
271 |
|
272 | .phab T123 prev <term>
|
273 | .phab T123 prev
|
274 | .phab previous
|
275 | .phab prev
|
276 | This will return the last match in the Task T123 description
|
277 | that begins with a [x] (a checked checkbox)
|
278 | if a <term> is provided, it will match the last line
|
279 | that begins with '[x] term'
|
280 | permission: phuser
|
281 |
|
282 | .phab T123 check <term>
|
283 | .phab T123 check
|
284 | .phab check
|
285 | .phab check! <term>
|
286 | .phab check!
|
287 | .phab check! + <comment>
|
288 | This will update the description of T123
|
289 | and replace the checkbox line with a checked box '[x]'
|
290 | If a term is provided, the first matching line will be the checked one
|
291 | If the '!' is added, it will also return the next unchecked checkbox
|
292 | If a '+' is added at the end of any above syntax, it will append a comment
|
293 | in the modification
|
294 | permission: phuser
|
295 |
|
296 | .phab T123 uncheck <term>
|
297 | .phab T123 uncheck
|
298 | .phab uncheck
|
299 | .phab uncheck! <term>
|
300 | .phab uncheck!
|
301 | .phab uncheck! + <comment>
|
302 | This will update the description of T123
|
303 | and replace the checked checkbox line with a checked box '[ ]'
|
304 | If a term is provided, the last matching line will be the unchecked one
|
305 | If the '!' is added, it will also return the previous checked checkbox
|
306 | If a '+' is added at the end of any above syntax, it will append a comment
|
307 | in the modification
|
308 | permission: phuser
|
309 |
|
310 | .phab user <someone>
|
311 | will check is <someone> is linked to his Phabricator account
|
312 | (using email address)
|
313 | permission: phuser
|
314 |
|
315 | .phab me as <email@example.com>
|
316 | registers your email in the bot. You need to specify the email address
|
317 | registered in Phabricator
|
318 | permission: phuser
|
319 |
|
320 | .phab user <someone> = <email@example.com>
|
321 | registers email for another user, follows the same concept as
|
322 | .phab me as ..
|
323 | permission: phadmin
|
324 |
|
325 | .phab count <project>
|
326 | return the number of tasks in the given <project>
|
327 | permission: all
|
328 |
|
329 | .phab version
|
330 | displays the version of hubot-phabs that is installed
|
331 | permission: all
|
332 |
|
333 | .phid <phid>
|
334 | .phid <name>
|
335 | When provided a PHID-*, gives the name and uri for a given PHID (mostly for arcanist use)
|
336 | When provided an item name (ie. T123), returns the PHID
|
337 | permission: all
|
338 |
|
339 |
|
340 | ### Templates feature
|
341 |
|
342 | There is also a way to specify a list of templates for creating new Tasks with prefilled descriptions. Any task can be used as a template, whatever the status, as far as they are readable by the bot user. Typically those can be relevant closed Tasks form the past that we fit for templating.
|
343 |
|
344 | The management of those templates is done with the `.pht` command:
|
345 |
|
346 | .pht new <name> T123
|
347 | creates a new template named <name>, using the task T123 as a template
|
348 | permission: phadmin
|
349 |
|
350 | .pht show <name>
|
351 | .pht info <name>
|
352 | shows what task is used as a template
|
353 | permission: phuser
|
354 |
|
355 | .pht search <term>
|
356 | .pht list <term>
|
357 | search through templates which names contain <term>
|
358 | If <term> is omitted, it just retruns the whole list
|
359 | of all templates
|
360 | permission: phuser
|
361 |
|
362 | .pht remove <name>
|
363 | removes template named <name> from the brain memory
|
364 | permission: phadmin
|
365 |
|
366 | .pht update <name> T321
|
367 | updated template named <name> with the new template task T321
|
368 | permission: phadmin
|
369 |
|
370 | .pht rename <name> <newname>
|
371 | rename the template named <name> with <newname>
|
372 | permission: phadmin
|
373 |
|
374 |
|
375 | ### Admin features
|
376 |
|
377 | Some configuration variables are stored the brain. They are managed by the phabs_admin module, driven with the `.phad` command. **note** the syntax changed in v1.5.1
|
378 |
|
379 | .phad projects
|
380 | lists projects listed in brain
|
381 | permission: all
|
382 |
|
383 | .phad delete <project>
|
384 | .phad del <project>
|
385 | removes information about <projects> from the brain
|
386 | (useful when a project is deleted or renamed in phabricator)
|
387 | permission: phadmin
|
388 |
|
389 | .phad info <project>
|
390 | .phad show <project>
|
391 | gives info about <project>, including aliases, feeds and columns
|
392 | permission: all
|
393 |
|
394 | .phad refresh <project>
|
395 | refresh info for <project> form phabricator
|
396 | typically useful when there are new columns in a workboard
|
397 | permission: all
|
398 |
|
399 | .phad alias <project> as <alias>
|
400 | adds an alias <alias> to <project>. Aliases are unique
|
401 | permission: phadmin
|
402 |
|
403 | .phad forget <alias>
|
404 | removes the alias <alias>
|
405 | permission: phadmin
|
406 |
|
407 | .phad feed <project> to <room>
|
408 | .phad feeds <project> to <room>
|
409 | creates a feed for <project> to <room>.
|
410 | Feeds are comming from feed.http-hooks. Only tasks are included in this feed.
|
411 | permission: phadmin
|
412 |
|
413 | .phad remove <project> from <room>
|
414 | remove a feed
|
415 | permission: phadmin
|
416 |
|
417 | .phad feedall to <room>
|
418 | creates a catchall feed to <room>.
|
419 | Only tasks are included in this feed.
|
420 | permission: phadmin
|
421 |
|
422 | .phad removeall from <room>
|
423 | remove a catchall feed
|
424 | permission: phadmin
|
425 |
|
426 |
|
427 | ### Feeds feature
|
428 |
|
429 | A http endpoint is open for receiving feeds from `feed.http-hooks` as explained in https://secure.phabricator.com/T5462
|
430 |
|
431 | You can use the `.phad` commands to associate Projects to rooms. Each Feed Story will then be dispatched on one or several rooms according to the project the task belongs to. This only works with Tasks (for now).
|
432 |
|
433 | Note that the tasks from a subprojects are also announced in the feed for the parent project.
|
434 |
|
435 | The feed has an optional way to limit the IP of the sender, by setting the HUBOT_AUTHORIZED_IP_REGEXP env variable. If this variable is not set, there is not access control. It's a limited soft protection, if you really need a heavy secure protection, do something on your network for it.
|
436 |
|
437 |
|
438 | ### Hear feature
|
439 |
|
440 | There is a `.hear` feature that also will give information about items that are cited on channel. It tries to do precise pattern matching but sometimes there are some unfortunate coincidences. For example, we work with level3 and talk about it under L3 often. Or one of our project involves a V5. It's kind of annoying to have the bot react on those specific case, so it' possible to blacklist them.
|
441 |
|
442 | There is possibility to only react to certain item type too, by setting the `PHABRICATOR_ENABLED_ITEMS` environment variable. For example `PHABRICATOR_ENABLED_ITEMS="T,P,r"` will restrict reactions to only Tasks, Pastes and Commits items. If that env var is not declared, it will react to all known types.
|
443 |
|
444 | something about https://phabricator.example.com/T2#17207
|
445 | just talking about T123. did you see that one?
|
446 | the plugin will watch if it sees
|
447 | - T[0-9]+ for tasks (of Maniphest)
|
448 | - P[0-9]+ for pastes
|
449 | - F[0-9]+ for files
|
450 | - M[0-9]+ for mocks (of Pholio)
|
451 | - B[0-9]+ for builds (of Harbormaster)
|
452 | - L[0-9]+ for legalpads
|
453 | - V[0-9]+ for polls (of Slowvote)
|
454 | - r[A-Z]+[a-f0-9]+ for commit (of Diffusion)
|
455 | if it is in an url, it will reply with
|
456 | T2 - <title of the task>
|
457 | if it's not in an url it will reply with
|
458 | <task url> - <task title>
|
459 | NOTE: this call will record this Task id associated to you for 5 minutes
|
460 | it will just say nothing if the pattern matched is in the blacklist
|
461 | permission: all
|
462 |
|
463 | .phab bl T123
|
464 | this will add T123 to the blacklist
|
465 | permission: phuser
|
466 |
|
467 | .phab unbl T123
|
468 | this will remove T123 from the blacklist
|
469 | permission: phuser
|
470 |
|
471 | Development
|
472 | --------------
|
473 |
|
474 | ### Changelog
|
475 |
|
476 | All changes are listed in the [CHANGELOG](CHANGELOG.md)
|
477 |
|
478 | ### Testing
|
479 |
|
480 | npm install
|
481 |
|
482 | # will run make test and coffeelint
|
483 | npm test
|
484 |
|
485 | # or
|
486 | make test
|
487 |
|
488 | # or, for watch-mode
|
489 | make test-w
|
490 |
|
491 | # or for more documentation-style output
|
492 | make test-spec
|
493 |
|
494 | # and to generate coverage
|
495 | make test-cov
|
496 |
|
497 | # and to run the lint
|
498 | make lint
|
499 |
|
500 | # run the lint and the coverage
|
501 | make
|
502 |
|
503 |
|
504 | ### Contribute
|
505 |
|
506 | Feel free to open a PR if you find any bug, typo, want to improve documentation, or think about a new feature.
|
507 |
|
508 | Gandi loves Free and Open Source Software. This project is used internally at Gandi but external contributions are **very welcome**.
|
509 |
|
510 | Attribution
|
511 | -----------
|
512 |
|
513 | ### Authors
|
514 |
|
515 | - [@mose](https://github.com/mose) - author and maintainer
|
516 |
|
517 | ### License
|
518 |
|
519 | This source code is available under [MIT license](LICENSE).
|
520 |
|
521 | ### Copyright
|
522 |
|
523 | Copyright (c) 2016 - Gandi - https://gandi.net
|