2.5.14.11. HipchatStatusPush¶

class buildbot.reporters.hipchat.HipchatStatusPush¶

from buildbot.plugins import reporters

hs = reporters.HipchatStatusPush('private-token', endpoint='https://chat.yourcompany.com')
c['services'].append(hs)

HipchatStatusPush publishes a custom message using Hipchat API v2. The message is published to a user and/or room in Hipchat,

It requires txrequests package to allow interaction with Hipchat API.

It uses API token auth, and the token owner is required to have at least message/notification access to each destination.

HipchatStatusPush(auth_token, endpoint="https://api.hipchat.com",

builder_room_map=None, builder_user_map=None,

wantProperties=False, wantSteps=False, wantPreviousBuild=False, wantLogs=False)

Parameters

auth_token (string) – Private API token with access to the “Send Message” and “Send Notification” scopes. (can be a Secret)
endpoint (string) – (optional) URL of your Hipchat server. Defaults to https://api.hipchat.com
builder_room_map (dictionary) – (optional) If specified, will forward events about a builder (based on name) to the corresponding room ID.
builder_user_map (dictionary) – (optional) If specified, will forward events about a builder (based on name) to the corresponding user ID.
wantProperties (boolean) – (optional) include ‘properties’ in the build dictionary
wantSteps (boolean) – (optional) include ‘steps’ in the build dictionary
wantLogs (boolean) – (optional) include ‘logs’ in the steps dictionaries. This needs wantSteps=True. This dumps the full content of logs.
wantPreviousBuild (boolean) – (optional) include ‘prev_build’ in the build dictionary
verify (boolean) – disable ssl verification for the case you use temporary self signed certificates
debug (boolean) – logs every requests and their response

Note

No message will be sent if the message is empty or there is no destination found.

Note

If a builder name appears in both the room and user map, the same message will be sent to both destinations.

Json object spec¶

The default json object contains the minimal required parameters to send a message to Hipchat.

{
    "message": "Buildbot started/finished build MyBuilderName (with result success) here: http://mybuildbot.com/#/builders/23",
    "id_or_email": "12"
}

If you require different parameters, the Hipchat reporter utilizes the template design pattern and will call getRecipientList getMessage getExtraParams before sending a message. This allows you to easily override the default implementation for those methods. All of those methods can be deferred.

Method signatures:

buildbot.reporters.hipchat.getRecipientList(self, build, event_name)¶

Parameters

build – A Build object
event_name (string) – the name of the event trigger for this invocation. either ‘new’ or ‘finished’

Returns

Deferred

The deferred should return a dictionary containing the key(s) ‘id_or_email’ for a private user message and/or ‘room_id_or_name’ for room notifications.

buildbot.reporters.hipchat.getMessage(self, build, event_name)¶

Parameters

build – A Build object
event_name (string) – the name of the event trigger for this invocation. either ‘new’ or ‘finished’

Returns

Deferred

The deferred should return a string to send to Hipchat.

buildbot.reporters.hipchat.getExtraParams(self, build, event_name)¶

Parameters

build – A Build object
event_name (string) – the name of the event trigger for this invocation. either ‘new’ or ‘finished’

Returns

Deferred

The deferred should return a dictionary containing any extra parameters you wish to include in your JSON POST request that the Hipchat API can consume.

Here’s a complete example:

class MyHipchatStatusPush(HipChatStatusPush):
    name = "MyHipchatStatusPush"

    # send all messages to the same room
    def getRecipientList(self, build, event_name):
        return {
            'room_id_or_name': 'AllBuildNotifications'
        }

    # only send notifications on finished events
    def getMessage(self, build, event_name):
        event_messages = {
            'finished': 'Build finished.'
        }
        return event_messages.get(event_name, '')

    # color notifications based on the build result
    # and alert room on build failure
    def getExtraParams(self, build, event_name):
        result = {}
        if event_name == 'finished':
            result['color'] = 'green' if build['results'] == 0 else 'red'
            result['notify'] = (build['results'] != 0)
        return result