Provided by: kgb-bot_1.33-2ubuntu1_all 
NAME
KGB_protocol - specification of the client-server communication protocol
DESCRIPTION
The protocol used by the KGB collaboration service is based on JSON-RPC (<http://json-rpc.org/>). KGB service helps collaboration by relaying notifications about commits in a version control system to IRC. It consists of client, hooked to the version control system which sends information about changes to the server, and a server, listening for client's notifications and relaying them on configured IRC channels.
AUTHENTICATION
Message content is authenticated by using two HTTP headers. The X-KGB-Project header must contain the
project ID, as defined in server's configuration. The X-KGB-Auth header must contain a SHA1 hash (in
hexadecimal notation) calculated over the shared secret, the project ID and the JSON-encoded message.
Upon receiving the HTTP request the server calculates the hash using the supplied project ID, the server
copy of the shared secret for that project and the content of the HTTP request. If the hash matches the
one provided in the X-KGB-Auth header, the authentication succeeds and the request is processed.
Otherwise an error is returned.
METHODS
commit_v4 arguments
This method takes information about a single commit and relays it to IRC. arguments is a map with the
members described below. Any additional members are ignored.
commit_id string
A string identifying the commit in the version control system. Git (short) hash, Subversion revision
number, this kind of thing.
rev_prefix string
A string to prepend to the commit ID when displaying on IRC. "r" is particularly useful for
Subversion repositories.
author string
A string representing the commit author.
branch string
A string representing the commit branch.
module string
A string representing the commit module or sub-project.
commit_log string
The commit message.
changes list of strings
List of changes files/directories in the commit. Each string is a path, optionaly prepended with
"(A)" for added paths, "(M)" for modified paths and "(D)" for deleted paths. If no prefix is given
modification is assumed. An additional plus sign flags property changes (Specific to Subversion
term), e.g. "(M+)".
extra map
A map with additional parameters. Currently supported members are:
web_link
A URL with commit details (e.g. gitweb or viewvc).
use_irc_notices
A flag whether to use IRC notices instead of regular messages.
use_color
A flag whether to use colors when sending commit notifications. Defaults to 1.
relay_message message
This method takes only one string argument which is the message to relay to IRC. There are no
restrictions or requirements to the message content, which is relayed verbatim to project's IRC channels.
ERRORS
Errors reported on HTTP level
Authentication errors use HTTP code 401, while other errors -- bad or missing headers and problems with
the JSON data use HTTP code 400.
The error text is in the reason phrase of the HTTP status line (see RFC 2616, section 6.1).
Errors reported on JSON-RPC level
After successful authentication and decoding of the JSON request, all the errors are reported as mandated
by the JSON-RPC specification.
AUTHOR
Damyan Ivanov dmn@debian.org
COPYRIGHT & LICENSE
Copyright (C) 2012 Damyan Ivanov
This program is free software; you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write
to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.