How to package Buildbot plugins

If you customized an existing component (see Customization) or created a new component that you believe might be useful for others, you have two options:

  • submit the change to the Buildbot main tree, however you need to adhere to certain requirements (see Buildbot Coding Style)
  • prepare a Python package that contains the functionality you created

Here we cover the second option.

Package the source

To begin with, you must package your changes. If you do not know what a Python package is, these two tutorials will get you going:

The former is more recent and, while it addresses everything that you need to know about Python packages, is still work in progress. The latter is a bit dated, though it was the most complete guide for quite some time available for Python developers looking to package their software.

You may also want to check the sample project, which exemplifies the best Python packaging practices.

Making the plugin package

Buildbot supports several kinds of pluggable components:

  • buildslave
  • changes
  • schedulers
  • steps
  • status
  • util

which are described in Plugin Infrastructure in Buildbot.

Once you have your component packaged, it's quite straightforward: you just need to add a few lines to the entry_points parameter of your call of setup function in setup.py file:

setup(
    ...
    entry_points = {
        ...,
        'buildbot.kind': [
            'PluginName = PluginModule:PluginClass'
        ]
    },
    ...
)

(You might have seen different ways to specify the value for entry_points, however they all do the same thing. Full description of possible ways is available in setuptools documentation.)

After the setup.py file is updated, you can build and install it:

$ python setup.py build
$ sudo python setup.py install

(depending on your particular setup, you might not need to use sudo).

After that the plugin should be available for Buildbot and you can use it in your master.cfg as:

from buildbot.kind import PluginName

... PluginName ...

Publish the package

This is the last step before the plugin is available to others.

Once again, there is a number of options available for you:

  • just put a link to your version control system
  • prepare a source tarball with the plugin (python setup.py sdist)
  • or publish it on PyPI

The last option is probably the best one since it will make your plugin available pretty much to all Python developers.

Once you have published the package, please send a link to buildbot-devel mailing list, so we can include a link to your plugin to Plugin Infrastructure in Buildbot.