Testing/CI/Integrated

QEMU supports a number of different public CI systems to maximise testing coverage of code submitted to QEMU.

By testing code via these CI systems prior to submission, contributors can reduce the burden on QEMU maintainers and eliminate delays in getting work accepted for merge.

Use of the CI systems prior to submission is NOT mandatory, but is encouraged especially for large / complex changes which have higher risk of causing build failures.

This document describes a way to setup personal accounts on public CI systems to facilitate pre-submission testing.

GitLab CI setup

QEMU considers GitLab to be the primary CI system, and as such new CI jobs will be placed on GitLab whenever technically possible. Thus creating an account on GitLab is the recommended first step.

GitLab CI currently provides container based build environments, using container images define in QEMU's repo under tests/docker/dockerfiles. This is capable of covering all Linux distros on the x86_64 architecture, and cross-builds for Windows using the Mingw64 toolchains, and non-x86 architecture cross-builds using GCC. This is provides a solid baseline for code contributions with the most widely used platforms for QEMU.

Start off by creating a fork of the primary QEMU repository. This will give you a public repo which you should add as a remote in your local clone

 $ git remote add gitlab https://gitlab.com/YOUR-USER-NAME/qemu

Whenever a branch containing work needs testing it can be pushed to this remote

 $ git push gitlab +branch-name

Use of the "+" in front of the branch name forces it to replace the previously pushed branch contents, which is what will typically be required if your local branch is being rebased frequently.

Immediately after the branch has been pushed, a CI pipeline for this branch will be scheduled. If it fails GitLab will send an email notification with the details. Its progress can be monitored at the URL https://gitlab.com/YOUR-USER-NAME/qemu/-/pipelines

GitHub setup

QEMU does not use GitHub CI services, however, the Cirrus CI system has a mandatory dependency on GitHub, and Travis CI can optionally use GitHub.

Start off by creating a fork of the primary QEMU repository.

There are now two options to choose between

Manual pushing

Add as the forked repo a remote in your local clone

 $ git remote add github https://github.com/YOUR-USER-NAME/qemu

Whenever a branch containing work needs testing via GitHub it can be pushed to this remote

 $ git push github +branch-name

Use of the "+" in front of the branch name forces it to replace the previously pushed branch contents, which is what will typically be required if your local branch is being rebased frequently.

Automatic mirroring

GitLab supports automatically mirroring repos to GitHub. By utilizing this feature it is not necessary to directly interact with GitHub at all.

Note that the mirroring process will force replace anything you have stored in your GitHub mirror already. Be careful if you've previously used GitHub to store any important work for QEMU

Note there is a mandatory 5 minute minimum time between mirroring attempts. IOW if pushing changes to GitLab more frequently than every 5 minutes, the GitHub sync can be delayed. A worst case delay can be about 10 minutes. If this is a problem it is still possible to manually push to GitHub directly until the mirror catches up.

In the GitHub web UI, from your account icon in the top right of the page, navigate to the "Settings -> Developer Settings -> Personal access tokens" page. On this page create a new access token and select the "public_repo" permission bit. Make a copy of the token that is displayed.

Switch back to your fork of the QEMU repository in GitLab (ie https://gitlab.com/YOUR-USER-NAME/qemu) and navigate to "Settings -> Repository -> Mirroring repositories".

Enter the URL of your QEMU GitHub fork, including your username in the URL e.g.

 $  https://YOUR-USER-NAME@github.com/YOUR-USER-NAME/qemu

select the mirroring direction as "push", and enter your GitHub access token as the password. Be careful if highlighting the token with the mouse to cut+paste as it is liable to pick up extra whitespace. Use the clipboard icon to copy it instead.

After submitting the form the mirroring should be tested by selecting the "Update now" button.

Cirrus CI setup

The Cirrus CI system covers some gaps that cannot be tested via GitLab CI. In particular it provides native build environments for FreeBSD 12, macOS X and Windows (MSys2). Thus adding use of Cirrus CI identifies the main OS portability problems that contributors are likely to encounter in their code.

Cirrus CI currently only integrates with GitHub, and using your GitHub account for signup / login, and then running builds when changes are pushed to GitHub repos.

IOW, to enable use of Cirrus CI, configure GitHub as described above. Using automatic mirroring from GitLab will allow both GitLab CI and Cirrus CI jobs to be triggered with a single push to GitLab.

Travis CI setup

The Travis CI system covers some gaps that cannot be tested via GitLab and Cirrus CI. In particular it provides non-x86 architecture build environments for arm64, s390x and ppc64le. While the GitLab CI can build test these architectures using cross compilation, the Travis CI environment enables execution of unit tests too.

Travis CI can integrate with either GitLab or GitHub.

GitLab integration

If signing into Travis CI using GitLab, it will require extensive permissions to the GitLab account which some contributors may not be happy with. These permissions enable better integration with GitLab though, with CI results appearing in the GitLab pipeline as an extra stage.

After signing in with Travis CI with GitLab, navigate to the repositories page and activate the "qemu" repository. Travis should now trigger builds when pushing to GitLab.

GitHub integration

If signing into Travis CI using GitHub, only read only permissions are required to the GitHub account.

To use this approach, first configure GitHub as describe above.

After signing in with Travis CI with GitLab, navigate to the repositories page and activate the "qemu" repository. Travis should now trigger builds when pushing to GitHub. The results of these builds are only visible via the Travis CI web interface.