UNPKG

23.3 kBMarkdownView Raw
1Hubot 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
11This 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
13When 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
15It 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
17This plugin is used in production internally at [Gandi](https://gandi.net) since 2016-07-13.
18
19Check 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
44Installation
45--------------
46In your hubot directory:
47
48 npm install hubot-phabs --save
49
50Then add `hubot-phabs` to `external-scripts.json`
51
52Next you need to create a `bot` user in Phabricator and grab its api key.
53
54
55Permission system
56-------------------
57
58By default every action is usable by any user. But you can follow the optional permission system by using the `hubot-auth` module.
59
60There 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
74If 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
76Configuration
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). If set to "0" there is memory on the last task remembered. If set to "-" the memory is never expired.
82
83If 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
87You 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- `PHABRICATOR_FEED_EVERYTHING` - if set to a value that is not '0' (like 1 or yes), then the feedall feature will not only announce tasks. Note that this option only applies to the `.ph feedall to <room>` case, not to specific projects feeds.
91
92
93Features
94----------------
95
96The `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
101Typical 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
107Available 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
120There 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
136It 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
142To 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
148Currently 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
159Commands 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
161Requests 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 [all] [limit] <project> <search terms>
164 will grab the 3 newest matches in tasks matching search terms and included in project.
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 - if the 'all' prefix is used, it will also search in task that are not in status 'open'
169 - if the limit is specified, it has to be a number. without limit the default is 3
170 remember that phabricator search api has a hard limit of 100 in any case
171 (so '.phab 1000 <project> <term>' will only return 100 results anyways)
172 permission: all
173
174 .phab [all] [limit] search <search terms>
175 will grab the 3 newest matches in tasks matching search terms.
176 Same rules apply as the search per project/tag.
177 permission: all
178
179 .phab new <project> <task title>
180 .phab new <project> <task title> = <description>
181 creates a new task in an arbitrary project.
182 A project alias can also be used.
183 The new task will be created in the default column of the project board.
184 The issuer of the command will be added in the list of subscribers
185 for the newly created task.
186 The <description> is optional, and will be used as description if provided
187 NOTE: this call will record this Task id associated to you for 1 hour
188 permission: phuser
189
190 .phab new <project>:<template> <task title>
191 .phab new <project>:<template> <task title> = <description>
192 creates a new task using a template.
193 if a description is provided, it will prepend the template description
194 For the rest, it behaves like the .phab new command
195 permission: phuser
196
197 .phab paste <new paste title>
198 creates a new paste and provide the link to edit it
199 permission: phuser
200
201 .phab T123
202 .phab
203 gives the status, priority and owner of the task xxx
204 NOTE: this call will record this Task id associated to you for 1 hour
205 permission: all
206
207 .phab T123 + <some comment>
208 .phab + <some comment>
209 adds a comment to task Txxx (or the one in short memory).
210 permission: phuser
211
212 .phab T123 in tag1
213 .phab T123 not in tag1
214 .phab T123 in tag1 in tag2 not in tag3 in tag4
215 adds or remove tags from tasks. Tags are also known as projects
216 permission: phuser
217
218 .phab T123 is open
219 .phab T123 is broken
220 .phab is low
221 .phab low
222 .phab is low = this is a reason
223 .phab is low + this is a reason
224 Changes status or priority for task Txxx. the 'is' is optional.
225 If the optional '=' or '+' is used, it will add a comment to that change
226 Available statuses are:
227 - open, opened -> open
228 - resolved, resolve, closed, close -> resolved
229 - wontfix, noway -> wontfix
230 - invalid, rejected -> invalid
231 - spite, lame -> spite
232 Available priorities are
233 - broken, unbreak -> Unbreak Now!
234 - none, unknown, triage -> Needs Triage
235 - high, urgent -> High
236 - normal -> Normal
237 - low -> Low
238 - wish, wishlist -> Whishlist
239 NOTE: this call will record this Task id associated to you for 1 hour
240 permission: phuser
241
242 .phab T123 on <someone>
243 .phab for <someone>
244 assigns the given task to a user (or the given user to the task,
245 which is exactly the same).
246 The 'for' and 'on' conjunctions are inter-changeable.
247 You can use 'me' as username and it will substitute your username
248 NOTE: this call will record this Task id associated to you for 1 hour
249 permission: phuser
250
251 .phab T123 to <column>
252 .phab to <column>
253 .phab T123 to <column> + some comment
254 .phab T123 to <column> = some comment
255 moves the task on the board to the column matching the <column>
256 the matching will take the first match.
257 A comment can optionaly be added
258 permission: phuser
259
260 .phab T123 sub <user>
261 .phab sub <user>
262 .phab T123 sub <user> + some comment
263 .phab T123 unsub <user> = some comment
264 subscribes and unsubscribes users to tasks.
265 A comment can optionally be added.
266 You can use 'me' as username and it will substitute your username
267 permission: phuser
268
269 .phab T123 on <someone> is low is open to <column>
270 starting with `v2.2.0` it's possible to combine several commands to
271 change a task. It detects actions to be taken according to the conjunction used:
272 - on - change owner
273 - for - change owner (alias to on)
274 - is - change status or priority
275 - in - change tag/project (add a tag)
276 - not in - change tag/project (remove a tag)
277 - to - change column
278 - sub - subscribes user
279 - unsub - unsubscribes user
280 permission: phuser
281
282 .phab T123 next <term>
283 .phab T123 next
284 .phab next
285 This will return the first match in the Task T123 description
286 that begins with a [ ] (a checkbox)
287 if a <term> is provided, it will match the first line
288 that begins with '[ ] term'
289 the first word on the line, just after the checkbox, is used
290 as a keyword, but it's totally optional
291 permission: phuser
292
293 .phab T123 prev <term>
294 .phab T123 prev
295 .phab previous
296 .phab prev
297 This will return the last match in the Task T123 description
298 that begins with a [x] (a checked checkbox)
299 if a <term> is provided, it will match the last line
300 that begins with '[x] term'
301 permission: phuser
302
303 .phab T123 check <term>
304 .phab T123 check
305 .phab check
306 .phab check! <term>
307 .phab check!
308 .phab check! + <comment>
309 This will update the description of T123
310 and replace the checkbox line with a checked box '[x]'
311 If a term is provided, the first matching line will be the checked one
312 If the '!' is added, it will also return the next unchecked checkbox
313 If a '+' is added at the end of any above syntax, it will append a comment
314 in the modification
315 permission: phuser
316
317 .phab T123 uncheck <term>
318 .phab T123 uncheck
319 .phab uncheck
320 .phab uncheck! <term>
321 .phab uncheck!
322 .phab uncheck! + <comment>
323 This will update the description of T123
324 and replace the checked checkbox line with a checked box '[ ]'
325 If a term is provided, the last matching line will be the unchecked one
326 If the '!' is added, it will also return the previous checked checkbox
327 If a '+' is added at the end of any above syntax, it will append a comment
328 in the modification
329 permission: phuser
330
331 .phab user <someone>
332 will check is <someone> is linked to his Phabricator account
333 (using email address)
334 permission: phuser
335
336 .phab me as <email@example.com>
337 registers your email in the bot. You need to specify the email address
338 registered in Phabricator
339 permission: phuser
340
341 .phab user <someone> = <email@example.com>
342 registers email for another user, follows the same concept as
343 .phab me as ..
344 permission: phadmin
345
346 .phab count <project>
347 return the number of tasks in the given <project>
348 permission: all
349
350 .phab version
351 displays the version of hubot-phabs that is installed
352 permission: all
353
354 .phid <phid>
355 .phid <name>
356 When provided a PHID-*, gives the name and uri for a given PHID (mostly for arcanist use)
357 When provided an item name (ie. T123), returns the PHID
358 permission: all
359
360
361### Templates feature
362
363There 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.
364
365The management of those templates is done with the `.pht` command:
366
367 .pht new <name> T123
368 creates a new template named <name>, using the task T123 as a template
369 permission: phadmin
370
371 .pht show <name>
372 .pht info <name>
373 shows what task is used as a template
374 permission: phuser
375
376 .pht search <term>
377 .pht list <term>
378 search through templates which names contain <term>
379 If <term> is omitted, it just retruns the whole list
380 of all templates
381 permission: phuser
382
383 .pht remove <name>
384 removes template named <name> from the brain memory
385 permission: phadmin
386
387 .pht update <name> T321
388 updated template named <name> with the new template task T321
389 permission: phadmin
390
391 .pht rename <name> <newname>
392 rename the template named <name> with <newname>
393 permission: phadmin
394
395
396### Admin features
397
398Some 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
399
400 .phad projects
401 lists projects listed in brain
402 permission: all
403
404 .phad delete <project>
405 .phad del <project>
406 removes information about <projects> from the brain
407 (useful when a project is deleted or renamed in phabricator)
408 permission: phadmin
409
410 .phad info <project>
411 .phad show <project>
412 gives info about <project>, including aliases, feeds and columns
413 permission: all
414
415 .phad info <parent> / <project>
416 .phad show <parent> / <project>
417 gives info about <project> given that it is a subproject or milestone of <parent>,
418 retunred information includes aliases, feeds and columns
419 permission: all
420
421 .phad refresh <project>
422 refresh info for <project> form phabricator
423 typically useful when there are new columns in a workboard
424 permission: all
425
426 .phad alias <project> as <alias>
427 adds an alias <alias> to <project>. Aliases are unique
428 permission: phadmin
429
430 .phad forget <alias>
431 removes the alias <alias>
432 permission: phadmin
433
434 .phad feed <project> to <room>
435 .phad feeds <project> to <room>
436 creates a feed for <project> to <room>.
437 Feeds are comming from feed.http-hooks. Only tasks are included in this feed.
438 permission: phadmin
439
440 .phad remove <project> from <room>
441 remove a feed
442 permission: phadmin
443
444 .phad feedall to <room>
445 creates a catchall feed to <room>.
446 Only tasks are included in this feed
447 unless the var PHABRICATOR_FEED_EVERYTHING is set and is not set to '0'
448 permission: phadmin
449
450 .phad removeall from <room>
451 remove a catchall feed
452 permission: phadmin
453
454
455### Feeds feature
456
457A http endpoint is open for receiving feeds from `feed.http-hooks` as explained in https://secure.phabricator.com/T5462
458
459You 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).
460
461Note that the tasks from a subprojects are also announced in the feed for the parent project.
462
463The 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.
464
465Since 2.4.1, users can also set private alerts on tasks they own or are subscribed to.
466
467 .phab me set alerts
468 will send a private message for each task the caller owns or is subscribed to
469 (note: it only works on tasks for now)
470 permission: phuser
471
472 .phab <user> set alerts
473 same as with 'me' but with arbitrary user name, to enable their subscription to alerts
474 permission: phadmin
475
476 .phab me unset alerts
477 will disable alerts
478 permission: phuser
479
480 .phab <user> unset alerts
481 same as with 'me' but with arbitrary user name, to disable their subscription to alerts
482 permission: phadmin
483
484
485### Hear feature
486
487There 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.
488
489There 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.
490
491 something about https://phabricator.example.com/T2#17207
492 just talking about T123. did you see that one?
493 the plugin will watch if it sees
494 - T[0-9]+ for tasks (of Maniphest)
495 - P[0-9]+ for pastes
496 - D[0-9]+ for differential revisions
497 - F[0-9]+ for files
498 - M[0-9]+ for mocks (of Pholio)
499 - B[0-9]+ for builds (of Harbormaster)
500 - L[0-9]+ for legalpads
501 - V[0-9]+ for polls (of Slowvote)
502 - r[A-Z]+[a-f0-9]+ for commit (of Diffusion)
503 if it is in an url, it will reply with
504 T2 - <title of the task>
505 if it's not in an url it will reply with
506 <task url> - <task title>
507 NOTE: this call will record this Task id associated to you for 5 minutes
508 it will just say nothing if the pattern matched is in the blacklist
509 permission: all
510
511 .phab bl T123
512 this will add T123 to the blacklist
513 permission: phuser
514
515 .phab unbl T123
516 this will remove T123 from the blacklist
517 permission: phuser
518
519Development
520--------------
521
522### Changelog
523
524All changes are listed in the [CHANGELOG](CHANGELOG.md)
525
526### Testing
527
528 npm install
529
530 # will run make test and coffeelint
531 npm test
532
533 # or
534 make test
535
536 # or, for watch-mode
537 make test-w
538
539 # or for more documentation-style output
540 make test-spec
541
542 # and to generate coverage
543 make test-cov
544
545 # and to run the lint
546 make lint
547
548 # run the lint and the coverage
549 make
550
551
552### Contribute
553
554Feel free to open a PR if you find any bug, typo, want to improve documentation, or think about a new feature.
555
556Gandi loves Free and Open Source Software. This project is used internally at Gandi but external contributions are **very welcome**.
557
558Attribution
559-----------
560
561### Authors
562
563- [@mose](https://github.com/mose) - author and maintainer
564
565### License
566
567This source code is available under [MIT license](LICENSE).
568
569### Copyright
570
571Copyright (c) 2016 - Gandi - https://gandi.net