========================== 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: * http://packaging.ubuntu.com/html/ * https://wiki.ubuntu.com/UbuntuDevelopment **Setting up the system for ticket creation** The following steps are needed to be able to use the command line interface: .. code-block:: none 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. .. code-block:: none 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: .. code-block:: none 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: .. code-block:: none 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: none $ subunit-1to2 results.xml This produces a 'results.xml' file in the junitxml format.