1== 2CI 3== 4 5QEMU has configurations enabled for a number of different CI services. 6The most up to date information about them and their status can be 7found at:: 8 9 https://wiki.qemu.org/Testing/CI 10 11Custom CI/CD variables 12====================== 13 14QEMU CI pipelines can be tuned by setting some CI environment variables. 15 16Set variable globally in the user's CI namespace 17------------------------------------------------ 18 19Variables can be set globally in the user's CI namespace setting. 20 21For further information about how to set these variables, please refer to:: 22 23 https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project 24 25Set variable manually when pushing a branch or tag to the user's repository 26--------------------------------------------------------------------------- 27 28Variables can be set manually when pushing a branch or tag, using 29git-push command line arguments. 30 31Example setting the QEMU_CI_EXAMPLE_VAR variable: 32 33.. code:: 34 35 git push -o ci.variable="QEMU_CI_EXAMPLE_VAR=value" myrepo mybranch 36 37For further information about how to set these variables, please refer to:: 38 39 https://docs.gitlab.com/ee/user/project/push_options.html#push-options-for-gitlab-cicd 40 41Here is a list of the most used variables: 42 43QEMU_CI_AVOCADO_TESTING 44~~~~~~~~~~~~~~~~~~~~~~~ 45By default, tests using the Avocado framework are not run automatically in 46the pipelines (because multiple artifacts have to be downloaded, and if 47these artifacts are not already cached, downloading them make the jobs 48reach the timeout limit). Set this variable to have the tests using the 49Avocado framework run automatically. 50 51Jobs on Custom Runners 52====================== 53 54Besides the jobs run under the various CI systems listed before, there 55are a number additional jobs that will run before an actual merge. 56These use the same GitLab CI's service/framework already used for all 57other GitLab based CI jobs, but rely on additional systems, not the 58ones provided by GitLab as "shared runners". 59 60The architecture of GitLab's CI service allows different machines to 61be set up with GitLab's "agent", called gitlab-runner, which will take 62care of running jobs created by events such as a push to a branch. 63Here, the combination of a machine, properly configured with GitLab's 64gitlab-runner, is called a "custom runner". 65 66The GitLab CI jobs definition for the custom runners are located under:: 67 68 .gitlab-ci.d/custom-runners.yml 69 70Custom runners entail custom machines. To see a list of the machines 71currently deployed in the QEMU GitLab CI and their maintainers, please 72refer to the QEMU `wiki <https://wiki.qemu.org/AdminContacts>`__. 73 74Machine Setup Howto 75------------------- 76 77For all Linux based systems, the setup can be mostly automated by the 78execution of two Ansible playbooks. Create an ``inventory`` file 79under ``scripts/ci/setup``, such as this:: 80 81 fully.qualified.domain 82 other.machine.hostname 83 84You may need to set some variables in the inventory file itself. One 85very common need is to tell Ansible to use a Python 3 interpreter on 86those hosts. This would look like:: 87 88 fully.qualified.domain ansible_python_interpreter=/usr/bin/python3 89 other.machine.hostname ansible_python_interpreter=/usr/bin/python3 90 91Build environment 92~~~~~~~~~~~~~~~~~ 93 94The ``scripts/ci/setup/build-environment.yml`` Ansible playbook will 95set up machines with the environment needed to perform builds and run 96QEMU tests. This playbook consists on the installation of various 97required packages (and a general package update while at it). It 98currently covers a number of different Linux distributions, but it can 99be expanded to cover other systems. 100 101The minimum required version of Ansible successfully tested in this 102playbook is 2.8.0 (a version check is embedded within the playbook 103itself). To run the playbook, execute:: 104 105 cd scripts/ci/setup 106 ansible-playbook -i inventory build-environment.yml 107 108Please note that most of the tasks in the playbook require superuser 109privileges, such as those from the ``root`` account or those obtained 110by ``sudo``. If necessary, please refer to ``ansible-playbook`` 111options such as ``--become``, ``--become-method``, ``--become-user`` 112and ``--ask-become-pass``. 113 114gitlab-runner setup and registration 115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 116 117The gitlab-runner agent needs to be installed on each machine that 118will run jobs. The association between a machine and a GitLab project 119happens with a registration token. To find the registration token for 120your repository/project, navigate on GitLab's web UI to: 121 122 * Settings (the gears-like icon at the bottom of the left hand side 123 vertical toolbar), then 124 * CI/CD, then 125 * Runners, and click on the "Expand" button, then 126 * Under "Set up a specific Runner manually", look for the value under 127 "And this registration token:" 128 129Copy the ``scripts/ci/setup/vars.yml.template`` file to 130``scripts/ci/setup/vars.yml``. Then, set the 131``gitlab_runner_registration_token`` variable to the value obtained 132earlier. 133 134To run the playbook, execute:: 135 136 cd scripts/ci/setup 137 ansible-playbook -i inventory gitlab-runner.yml 138 139Following the registration, it's necessary to configure the runner tags, 140and optionally other configurations on the GitLab UI. Navigate to: 141 142 * Settings (the gears like icon), then 143 * CI/CD, then 144 * Runners, and click on the "Expand" button, then 145 * "Runners activated for this project", then 146 * Click on the "Edit" icon (next to the "Lock" Icon) 147 148Tags are very important as they are used to route specific jobs to 149specific types of runners, so it's a good idea to double check that 150the automatically created tags are consistent with the OS and 151architecture. For instance, an Ubuntu 20.04 aarch64 system should 152have tags set as:: 153 154 ubuntu_20.04,aarch64 155 156Because the job definition at ``.gitlab-ci.d/custom-runners.yml`` 157would contain:: 158 159 ubuntu-20.04-aarch64-all: 160 tags: 161 - ubuntu_20.04 162 - aarch64 163 164It's also recommended to: 165 166 * increase the "Maximum job timeout" to something like ``2h`` 167 * give it a better Description 168