helga-jenkins 0.0.5

jenkins plugin for helga

A Jenkins plugin for helga chat bot

About

Helga is a Python chat bot. Full documentation can be found at http://helga.readthedocs.org.

This Jenkins plugin allows Helga to run Jenkins playbooks from IRC and return information when they succeed or fail. For example:

03:14 < alfredodeza> !jenkins ceph version=0.80.8.1 branch=rhcs-v0.80.8 release=stable clean=true
03:14 < helgabot> running: ceph jop at http://jenkins.example.com/job/ceph/323

Failed builds will report back minimal information with an optional paste of the log:

03:17 < helgabot> alfredodeza: build ceph/323 failed. Details at http://jenkins.example.com/job/ceph/323/console

Successful runs will also report back to the user:

03:19 < helgabot> alfredodeza: build ceph/323 suceeded!

Installation

This Jenkins plugin is available from PyPI, so you can simply install it with pip:

pip install helga-jenkins

If you want to hack on the helga-jenkins source code, in your virtualenv where you are running Helga, clone a copy of this repository from GitHub and run python setup.py develop.

Configuration

In your settings.py file (or whatever you pass to helga --settings), you can configure a few general things like credentials and Jenkins locations.

In most cases, the plugin will only be configured for a single Jenkins instance, but there is support for multiple instances if configured to do so.

Single Instance

A single instance can be configured as follows (listed with some defaults):

# simple authentication
JENKINS_USERNAME = "alfredodeza"
JENKINS_PASSWORD = "ElCapitano2"

# Jenkins url
JENKINS_URL = "http://jenkins.example.com"

# for multiple auth/tokens, define a 'credentials' dictionary
JENKINS_CREDENTIALS = {
  "alfredodeza": {
    "username": "adeza",
    "token": "33b3ffadgg3v61g1bfd6fd8543df50e4",
  }
}

For multiple users, it is useful to map IRC nicks to usernames in Jenkins, allowing a user to have different usernames (often the case).

Multiple Instances

For multiple instances, it is required to have defined a key that holds the information for connections and users:

# Multiple Jenkins
MULTI_JENKINS = {
  "test": {
      # URL is always required
      'url': 'http://test_jenkins.example.com',
      'credentials': {
        "alfredodeza": {
            "username": "adeza",
            "token": "33b3ffadgg3v61g1bfd6fd8543df50e4",
        },
        "ktdreyer": {
          "username": "kdreyer",
          "token": "44bh4gggg3dkjasdweiuhr780wer234ss",
        }
      },
  "prod": {
      # if no credentials per-user is supplied, define a global one that
      # any user can use
      'url': 'http://test_jenkins.example.com',
      'username': 'admin',
      'password': 'secret',
}

Note that each key in MULTI_JENKINS will equate to a supported command when invoking it on IRC, for example:

<alfredodeza> !ci test build test-job

Where test is a configured Jenkins instance. Or:

<alfredodeza> !ci prod build other-job

Either credentials (with IRC nicks as keys, as username and tokens) or username and password must exist, the bot will fallback from one to the other depending on what is defined and available to connect.

sub commands

There are a few commands that are allowed, you can trigger their exampe usage at any time with:

!ci help {command}

This is a list of all the available ones with a short description of what they do (most of them will require a job name argument at the very least):

• enable: Enable a disabled job.

• disable: Disable an enabled job.

• build: Trigger a job build, will probably need authentication.

• health: Report on the current health of a job.

• builds: Report on the last builds of a job