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