Koji/MessageBus

Koji can be configured to send notifications of events and state changes to a AMQP (qpid) broker. This page explains how to configure Koji to communicate with a message bus and documents the structure and contents of the messages it sends.

Configuration

Koji message bus integration is implemented via a Koji hub plugin, which registers a callback that is executed when certain events occur on the hub. To install the plugin, install the koji-hub-plugins package on the Koji hub machine. To enable the plugin, edit the Plugins entry of /etc/koji-hub/hub.conf so it contains messagebus. Make sure the Plugins entry is not commented out.

Configuration of the message bus plugin itself is handled by editing /etc/koji-hub/plugins/messagebus.conf. The [broker] section defines how to connect to the AMQP broker you want to use. auth can be any authentication type supported by the SASL configuration of the broker. If using auth = PLAIN, you must also provide a username and password, and it is highly recommended to set ssl = true. Otherwise you'll be sending your username and password over the network in plain text.

The [exchange] section determines where the plugin will send messages. The type option may be topic or headers. The exchange may already exist, or the plugin will create it, in which case the account being used to connect to the broker must have sufficient privileges to create exchanges.

If using a topic exchange, you can set the prefix of the message routing key with the prefix option in the [topic] section.

The body of the messages will be encoded in the format specified by the encoding option in the format section. Right now the only supported format is json.

Message Formats

The following table lists the events for which messages are sent out, the structure of the routing key (when using a topic exchange), the message headers (when using a headers exchange), and the fields present in the body of the message. All message bodies are json-encoded key/value maps.

Type	Routing Key	Message Headers	Body
PackageListChange	[prefix].PackageListChange.[tag name].[package name]	type (string): PackageListChange tag (string): tag name package (string): package name	action (string): add, update, block, unblock, or remove tag (map): tag info package (map): package info owner (int): owner ID block (bool) extra_arches (string) force (bool) update (bool)
TaskStateChange	[prefix].TaskStateChange.[task method].[attribute changed]	type (string): TaskStateChange method (string): task method attribute (string): attribute changed old (variable): previous value of attribute new (variable): current value of attribute	attribute (string): attribute changed old (variable): previous value of attribute new (variable): current value of attribute info (map): task info
BuildStateChange	[prefix].BuildStateChange.[attribute changed].[package name]	type (string): BuildStateChange name (string): package name version (string): build version release (string): build release attribute (string): attribute changed old (variable): previous value of attribute new (variable): current value of attribute	attribute (string): attribute changed old (variable): previous value of attribute new (variable): current value of attribute info (map): build info
Import	[prefix].Import.[import type]	type (string): Import importType (string): build, rpm, or image	type (string): build, rpm, or image if type == build: srpm (string) rpms (list) brmap (map): map of rpm paths -> buildroot ids task_id (int) build_id (int) build (map): build info logs (map): map of task arch -> list of log files if type == rpm: rpm (map): rpm info build (map): build info if type == image: image (map): image info
Tag or Untag	[prefix].[Tag or Untag].[tag name].[package name].[user name]	type (string): Tag or Untag tag (string): tag name name (string): package name version (string): build version release (string): build release user (string): user name	tag (map): tag info build (map): build info user (map): build info force (bool) if type == Untag: strict (bool)
RepoInit	[prefix].RepoInit.[tag name]	tag (string): tag name	tag (map): tag info with_src (bool) with_debuginfo (bool) event (int): event ID repo_id (int)
RepoDone	[prefix].RepoDone.[tag name]	tag (string): tag name	repo (map): repo info data (map): map of arch -> (uploadpath, [files]) expire (bool)