Using the Ubuntu CI Engine

As the Ubuntu CI Engine evolves through development, the usage will become more user friendly and more robust.

Prerequisites

The Ubuntu CI Engine current only processes source packages as input. These source packages will be uploaded unmodified into a Launchpad PPA. As a result, the source packages used as input must be signed by a user with permission to upload to the PPAs used by the Ubuntu CI Engine. These teams will be managed through Launchpad team membership granted via a CI team member.

Launchpad Setup

Prior to creating a source package to upload and a ticket, a user will need setup a Launchpad account and OpenPGP key:

Creating a Source Package

Once the account setup is complete, users can create source packages. A full tutorial on creating and modifying source packages are beyond the scope of this document. There are many Ubuntu development and packaging guides available including:

Setting up the system for ticket creation

The following steps are needed to be able to use the command line interface:

sudo add-apt-repository ppa:canonical-ci-engineering/ci-airline-phase-0
sudo apt-get update
sudo apt-get install uci-cli

Creating a Ticket

Ubuntu CI Engine requests, known as tickets, are created through a command line interface.

ubuntu-ci [-S|--url] create_ticket -t "Ticket name" -d "Ticket description" -b 123 -o user@example.com -s /full/path/to/_source.changes -s /full/path/to/_source.changes

This returns a ticket ID which can later be used to monitor and check for results. Once the ticket is created, the Ubuntu CI Engine does the rest. The ticket will be queued by the Ticket System and executed in FIFO (First In First Out) order. As the system is limited to processing one ticket at a time, it may take multiple hours for a single ticket to be completed.

Parts of a ticket submission

The general input specification for a ticket is one or more source packages and a list of binary package names to add to or remove from the image that will be generated. These are specified with the appropriate create_ticket arguments. The full set of required and optional create_ticket arguments are:

usage: ubuntu-ci [-h] [-v {1,2,3}] [-u URL] [-S]
               {create_ticket,update_ticket,status,get_image} ...

optional arguments:
  -h, --help            show this help message and exit
  -v {1,2,3}, --verbosity {1,2,3}
                      Verbosity level; 1=errors only, 2=verbose output,
                      3=very verbose output
  -u URL, --url URL     Development ticket system url
  -S, --staging
  -t TITLE, --title TITLE
                        Ticket title
  -d DESCRIPTION, --description DESCRIPTION
                        Ticket description
  -b BUG, --bug BUG     Related bug number
  -o OWNER, --owner OWNER
                        Email address of the ticket owner
  -s SOURCES, --sources SOURCES
                        Path to source.changes files. Source package files
                        (e.g. source.dsc, source.orig.tar.gz, etc.) are
                        required to be in the same directory as their
                        respective source.changes.
  -w, --wait            Do not queue the ticket for processing.
actions:
  {create_ticket,status,get_image}
                      commands
  create_ticket       Create a new ticket
  update_ticket       Update an existing ticket.
  status              Get ticket status. Use no flags for all tickets
  get_image           Retrieve the image produced by a ticket.

Note

The -t and -d arguments can be specified with a quoted text string.

Ticket Defaults

Images are produced from a default source image and series, which is currently based on Ubuntu 13.10 (saucy).

Specification of a source package

A source package is a standard Debian source package which may optionally contain dep8 autopackage tests. If autopackage tests are defined, they will be used to validate the image that is produced. All tests must pass for a ticket to complete CI successfully.

Every upload of a source package must include a version bump.

Monitoring a Ticket

As a ticket progresses through the Ubuntu CI Engine, the status of the ticket is updated to reflect it’s current processing step. This status can be checked via the web interface.

Collecting Ticket Results

Once a ticket is completed, it’s status will be updated appropriately and all build and test results and logs will be available via the web interface.

Exploiting Test Results

The test runner produces results in the subunit v1 format.

The subunit stream can be downloaded from the web interface and processed locally in different ways.

Note that the subunit stream contains the dep-8 test results.

The subunit v1 format is text only and as such can be read but it’s not especially user-friendly:

test: dsc0t-build
successful: dsc0t-build [ multipart
Content-Type: text/plain;charset=utf8
stderr
0^M
Content-Type: text/plain;charset=utf8
stdout
12^M
build: OK
run: OK
0^M
]

subunit provide filters to convert a stream into more readable outputs.

Converting to the python unittest format

$ subunit-1to2  <subunit.stream | subunit2pyunit

This filter is appropriate to inspect failures in tests and will produce (for example):

$ subunit-1to2  <fail.stream | subunit2pyunit
tests.test_pass
tests.test_pass ... ok
tests.test_fail
tests.test_fail ... FAIL
======================================================================
FAIL: tests.test_fail
tests.test_fail
----------------------------------------------------------------------
testtools.testresult.real._StringException: Traceback (most recent call last):
  File "tests.py", line 31, in test_fail
    self.assertTrue(False)
  File "/usr/lib/python2.7/unittest/case.py", line 424, in assertTrue
    raise self.failureException(msg)
AssertionError: False is not true


----------------------------------------------------------------------
Ran 2 tests in 0.001s

FAILED (failures=1)

Converting to the junitxml format

$ subunit-1to2  <subunit.stream | subunit2junitxml >results.xml

This produces a ‘results.xml’ file in the junitxml format.