mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-15 11:22:40 +01:00
82 lines
3.2 KiB
Text
82 lines
3.2 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.
|
||
|
|
|
||
|
|
= 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.
|
||
|
|
|
||
|
|
You can also write your own handlers, by extending
|
||
|
|
@{class:PhabricatorIRCHandler}.
|
||
|
|
|
||
|
|
= Conduit =
|
||
|
|
|
||
|
|
Some handlers (e.g., @{class:PhabricatorIRCObjectNameHandler}) need to read data
|
||
|
|
from Phabricator. They do this 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.
|