UNPKG

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