Fossil plugin for Buildbot

Fossil is a software configuration management system. This Buildbot plugin provides two classes for use in your Buildbot master.cfg:

  1. changes.FossilPoller polls a Fossil HTTP server for new checkins.

  2. steps.Fossil checks out a source revision from a Fossil repository before a build.

This plugin makes it possible to use Buildbot as a continuous integration server for projects being developed in a Fossil repository.

Installation

Install the buildbot-fossil package from PyPI on the machine running Buildbot:

pip install buildbot-fossil

The package is automatically registered as a Buildbot plugin, so the two new classes appear as buildbot.plugins.changes.FossilPoller and buildbot.plugins.steps.Fossil, ready to be used in the master.cfg configuration file.

Polling for commits

Buildbot learns about new commits from its change sources. Add a Fossil change source to master.cfg to poll for changes in a Fossil repository served over HTTP:

from buildbot.plugins import changes
...
c['change_source'] = changes.FossilPoller('https://fossil-scm.example/home')

By default, the Fossil repository is polled every 10 minutes using the JSON API.

class changes.FossilPoller(repourl: str, rss: bool = False, name: Optional[str] = None, pollInterval: int = 600, pollAtLaunch: bool = False, pollRandomDelayMin: int = 0, pollRandomDelayMax: int = 0)

Fossil SCM poller.

Regularly check the Fossil repository at repourl for new commits and submit them to the Buildbot master.

Parameters:

  • repourl – Base URL of the Fossil repository without a trailing /. Only HTTP and HTTPS URLs are supported.

  • rss – Use {repourl}/timeline.rss instead of Fossil’s JSON API to get new commits. JSON is preferred (and default) because RSS does not provide a list of changed files in a commit, but JSON support is not always configured in the Fossil server.

  • name – The name of the poller defaults to repourl, but can be changed with this parameter. This name is also used by Buildbot’s /change_hook/poller hook.

  • pollInterval – Interval between polls, in seconds.

  • pollAtLaunch – Poll immediately at launch instead of waiting a poll interval before the first poll.

  • pollRandomDelayMin – Set to randomize the polling interval to even out the load if there are many pollers to the same repository.

  • pollRandomDelayMax – Set to randomize the polling interval to even out the load if there are many pollers to the same repository.

Configuring an after-receive hook

Polling alone works fine, but it causes delays between committing a change and Buildbot noticing the change and testing it. The delays can be avoided by installing a Fossil after-receive hook which tells Buildbot to poll immediately.

The hook needs the URL where the Fossil repository is served (actually, the poller name), and the Buildbot URL. The curl command must be available:

#!/bin/sh
#
# Install: after-receive.sh --install /path/to/repo.fossil

if [ "$1" == "--install" ]; then
    sdir=$(cd "$(dirname "$0")" && pwd)
    fossil hook add -R "$2" --type after-receive --command "$sdir/after-receive.sh %R"
    exit
fi

repo="$(basename "$1" .fossil)"
name="http://my.fossil.example/$repo"
buildbot="https://server.example/buildbot"

curl -s "$buildbot/change_hook/poller?poller=$name"

Fossil does provide some information to an after-receive hook on stdin, but this script doesn’t need it since it just causes Buildbot to turn around and poll the Fossil server for any new changes.

Checking out sources on a worker

Before testing a Fossil commit on a Buildbot worker, the sources must be checked out on the worker. This is handled by the steps.Fossil build step which requires a fossil executable installed on the worker machines. The Fossil repository at {repourl} is cloned to a {workdir}.fossil file on the worker and checked out in the {workdir} directory.

See also the Buildbot documentation of source checkout operations.

class steps.Fossil(*args, **kwargs)

Check out a revision from the Fossil SCM.

Parameters:

  • repourl – URL of the upstream Fossil repository. This can be any URL supported by fossil clone.

  • mode – One of “full” or “incremental”. In the default “incremental” mode, build files are left in place in the workdir, and only fossil revert is used to clean up before fossil update checks out the new revision. This enables fast, incremental builds. In “full” mode, the workdir is cleaned up more thoroughly as specified by the method parameter.

  • method –

    How to clean up the workdir in “full” mode. One of “fresh”, “copy”, or “clobber”:

    • The “fresh” method runs fossil clean --verily to delete all unversioned files in workdir.

    • The “copy” method deletes the entire workdir directory tree and makes a new checkout from the cloned {workdir}.fossil repository.

    • The “clobber” method deletes both the cloned repository and the workdir and starts over with a new clone from repourl.