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:
- Create an https://launchpad.net/ account.
- Create and upload an OpenPGP key to Launchpad. Instructions are available at https://help.launchpad.net/YourAccount/ImportingYourPGPKey.
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.