mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-15 11:22:40 +01:00
7200040479
Summary: This is pretty simple and unpolished, but it's getting pretty big and it seems like a reasonable starting point. - Log chat in various "channels". - Conduit record and query methods. - IRCBot integration for IRC logging Major TODO: - Web UI is really unpolished and has no search, paging, anchor-linking, etc. Basically all presentation stuff, though. - I think the bot should have a map of channels to log with channel aliases? - The "channels" should probably be in a separate table. - The "authors" should probably be correlated to Phabricator accounts somehow, where possible. Test Plan: Used phabotlocal to log #phabricator. Reviewers: kdeggelman, btrahan, Koolvin Reviewed By: btrahan CC: aran, epriestley Maniphest Tasks: T837 Differential Revision: https://secure.phabricator.com/D1625
87 lines
3.6 KiB
Text
87 lines
3.6 KiB
Text
@title IRCBot Technical Documentation
|
|
@group irc
|
|
|
|
Configuring and extending the IRCBot.
|
|
|
|
= Overview =
|
|
|
|
Phabricator includes a simple IRC bot daemon, which is primarily intended as
|
|
an example of how you can write an external script that interfaces with
|
|
Phabricator over Conduit and does some kind of useful work. If you use IRC, you
|
|
can also have the bot hang out in your channel.
|
|
|
|
NOTE: The IRC bot is somewhat experimental and not very mature.
|
|
|
|
= Configuring the Bot =
|
|
|
|
The bot reads a JSON configuration file. You can find an example in:
|
|
|
|
resources/ircbot/example_config.json
|
|
|
|
These are the configuration values it reads:
|
|
|
|
- ##server## String, required, the server to connect to.
|
|
- ##port## Int, optional, the port to connect to (defaults to 6667).
|
|
- ##ssl## Bool, optional, whether to connect via SSL or not (defaults to
|
|
false).
|
|
- ##nick## String, nickname to use.
|
|
- ##user## String, optional, username to use (defaults to ##nick##).
|
|
- ##pass## String, optional, password for server.
|
|
- ##nickpass## String, optional, password for NickServ.
|
|
- ##join## Array, list of channels to join.
|
|
- ##handlers## Array, list of handlers to run. These are like plugins for the
|
|
IRCBot.
|
|
- ##conduit.uri##, ##conduit.user##, ##conduit.cert## Conduit configuration,
|
|
see below.
|
|
- ##notification.channels## Notification configuration, see below.
|
|
|
|
= Handlers =
|
|
|
|
You specify a list of "handlers", which are basically plugins or modules for
|
|
the IRC bot. These are the default handlers available:
|
|
|
|
- @{class:PhabricatorIRCProtocolHandler} This handler implements the raw IRC
|
|
protocol (e.g., responding with PONG when the server sends PING). You should
|
|
probably leave it in the handler list unless you implement the protocol
|
|
details yourself in another handler.
|
|
- @{class:PhabricatorIRCObjectNameHandler} This handler looks for users
|
|
mentioning Phabricator objects like "T123" and "D345" in chat, looks them
|
|
up, and says their name with a link to the object. Requires conduit.
|
|
- @{class:PhabricatorIRCDifferentialNotificationHandler} This handler posts
|
|
notifications about changes to revisions to IRC to the channels listed in
|
|
##notification.channels##.
|
|
- @{class:PhabricatorIRCLogHandler} This handler records chatlogs which can
|
|
be browsed in the Phabricator web interface.
|
|
|
|
You can also write your own handlers, by extending
|
|
@{class:PhabricatorIRCHandler}.
|
|
|
|
= Conduit =
|
|
|
|
Some handlers (e.g., @{class:PhabricatorIRCObjectNameHandler}) need to read data
|
|
from Phabricator over Conduit, Phabricator's HTTP API. You can use this method
|
|
to allow other scripts or programs to access Phabricator's data from different
|
|
servers and in different languages.
|
|
|
|
To allow the bot to access Conduit, you need to create a user that it can login
|
|
with. To do this, login to Phabricator as an administrator and go to
|
|
##People -> Create New Account##. Create a new account and flag them as a
|
|
"System Agent". Then in your configuration file, set these parameters:
|
|
|
|
- ##conduit.uri## The URI for your Phabricator install, like
|
|
##http://phabricator.example.com/##
|
|
- ##conduit.user## The username your bot should login to Phabricator with --
|
|
whatever you selected above, like ##phabot##.
|
|
- ##conduit.cert## The user's certificate, from the "Conduit Certificate" tab
|
|
in the user's administrative view.
|
|
|
|
Now the bot should be able to connect to Phabricator via Conduit.
|
|
|
|
= Starting the Bot =
|
|
|
|
The bot is a Phabricator daemon, so start it with ##phd##:
|
|
|
|
./bin/phd launch ircbot <absolute_path_to_config_file>
|
|
|
|
If you have issues you can try ##debug## instead of ##launch##, see
|
|
@{article:Managing Daemons with phd} for more information.
|