KGB-PROTOCOL(7p)

💅 NAME 💅

okay bestie, listen up — this is KGB_protocol, the whole entire spec for how the client and the server talk to each other 💖 (yes that's a 7p page, a whole perl manual page, we love that for us).

---

🌸 DESCRIPTION 🌸

So the protocol that the KGB collaboration service runs on? It's built on JSON-RPC (http://json-rpc.org/). That's the whole vibe fr fr.

And what does KGB actually do? It helps people collaborate by relaying notifications about commits in a version control system over to IRC ✨. It's two pieces working together:

• a client, hooked into the version control system, which sends info about changes to the server 🦋
• a server, which sits there listening for the client's notifications and relays them onto the configured IRC channels 👑

Two halves, one iconique friendship. periodt.

---

🔐 AUTHENTICATION 🔐

Message content gets authenticated using two HTTP headers. Not one. Two. She's thorough 💅

• The X-KGB-Project header must contain the project ID, exactly as it's defined in the server's configuration.
• The X-KGB-Auth header must contain a SHA1 hash — written out in hexadecimal notation — calculated over the shared secret, the project ID, and the JSON-encoded message.

Then when the HTTP request lands, the server does its little math: it calculates the hash using the project ID that was supplied, the server's own copy of the shared secret for that project, and the content of the HTTP request. If that hash matches the one in the X-KGB-Auth header, auth succeeds and the request gets processed 🎀. If it doesn't match? Error. That's it, that's the vibe check.

---

🛠️ METHODS 🛠️

📝 commit_v4 arguments

This method takes info about a single commit and relays it straight to IRC. The arguments is a map with the members listed below 👇. Any extra members you toss in? Ignored. Not even looked at. 💀

• commit_id string — a string identifying the commit in the version control system. Git (short) hash, Subversion revision number, that kind of thing ✨.
• rev_prefix string — a string to prepend to the commit ID when it's displayed 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 — the list of changed files/directories in the commit. Each string is a path, and it can optionally be prepended with:
  • (A) for added paths
  • (M) for modified paths
  • (D) for deleted paths

If you don't give any prefix, modification is assumed. And there's an extra plus sign that flags property changes (that's the Subversion-specific term, iykyk), like "(M+)".

• extra map — a map with additional parameters. Currently the supported members are:
  • web_link — a URL with commit details (like gitweb or viewvc 🔗).
  • use_irc_notices — a flag for whether to use IRC notices instead of regular messages.
  • use_color — a flag for whether to use colors when sending commit notifications. Defaults to 1 🌈.

📨 relay_message message

This method takes exactly one string argument, and that string is the message to relay to IRC. No restrictions, no requirements on the content — it gets relayed verbatim to the project's IRC channels. Say whatever, it's going through 💅.

💀 ERRORS 💀

Errors reported on HTTP level

• Authentication errors use HTTP code 401.
• Every other error — bad or missing headers, and problems with the JSON data — uses HTTP code 400.

The error text lives in the reason phrase of the HTTP status line 📌 (see RFC 2616, section 6.1).

Errors reported on JSON-RPC level

Once authentication has succeeded and the JSON request has been decoded, all the errors get reported exactly as the JSON-RPC specification mandates. No custom drama.

bestie not me having to break the bad news about 401 and 400 😭 but that's just how she works.

---

👑 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.

---

and that's the whole page bestie 🎀 this one's from perl v5.40.1, dated 2026-07-10, and yeah — it's literally KGB-PROTOCOL(7p). go off, you understood all of it, so proud 💖✨🦋