1.. _ci_var: 2 3Custom CI/CD variables 4====================== 5 6QEMU CI pipelines can be tuned by setting some CI environment variables. 7 8Set variable globally in the user's CI namespace 9------------------------------------------------ 10 11Variables can be set globally in the user's CI namespace setting. 12 13For further information about how to set these variables, please refer to:: 14 15 https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project 16 17Set variable manually when pushing a branch or tag to the user's repository 18--------------------------------------------------------------------------- 19 20Variables can be set manually when pushing a branch or tag, using 21git-push command line arguments. 22 23Example setting the QEMU_CI_EXAMPLE_VAR variable: 24 25.. code:: 26 27 git push -o ci.variable="QEMU_CI_EXAMPLE_VAR=value" myrepo mybranch 28 29For further information about how to set these variables, please refer to:: 30 31 https://docs.gitlab.com/ee/user/project/push_options.html#push-options-for-gitlab-cicd 32 33Setting aliases in your git config 34---------------------------------- 35 36You can use aliases to make it easier to push branches with different 37CI configurations. For example define an alias for triggering CI: 38 39.. code:: 40 41 git config --local alias.push-ci "push -o ci.variable=QEMU_CI=1" 42 git config --local alias.push-ci-now "push -o ci.variable=QEMU_CI=2" 43 44Which lets you run: 45 46.. code:: 47 48 git push-ci 49 50to create the pipeline, or: 51 52.. code:: 53 54 git push-ci-now 55 56to create and run the pipeline 57 58 59Variable naming and grouping 60---------------------------- 61 62The variables used by QEMU's CI configuration are grouped together 63in a handful of namespaces 64 65 * QEMU_JOB_nnnn - variables to be defined in individual jobs 66 or templates, to influence the shared rules defined in the 67 .base_job_template. 68 69 * QEMU_CI_nnn - variables to be set by contributors in their 70 repository CI settings, or as git push variables, to influence 71 which jobs get run in a pipeline 72 73 * nnn - other misc variables not falling into the above 74 categories, or using different names for historical reasons 75 and not yet converted. 76 77Maintainer controlled job variables 78----------------------------------- 79 80The following variables may be set when defining a job in the 81CI configuration file. 82 83QEMU_JOB_CIRRUS 84~~~~~~~~~~~~~~~ 85 86The job makes use of Cirrus CI infrastructure, requiring the 87configuration setup for cirrus-run to be present in the repository 88 89QEMU_JOB_OPTIONAL 90~~~~~~~~~~~~~~~~~ 91 92The job is expected to be successful in general, but is not run 93by default due to need to conserve limited CI resources. It is 94available to be started manually by the contributor in the CI 95pipelines UI. 96 97QEMU_JOB_ONLY_FORKS 98~~~~~~~~~~~~~~~~~~~ 99 100The job results are only of interest to contributors prior to 101submitting code. They are not required as part of the gating 102CI pipeline. 103 104QEMU_JOB_SKIPPED 105~~~~~~~~~~~~~~~~ 106 107The job is not reliably successsful in general, so is not 108currently suitable to be run by default. Ideally this should 109be a temporary marker until the problems can be addressed, or 110the job permanently removed. 111 112QEMU_JOB_PUBLISH 113~~~~~~~~~~~~~~~~ 114 115The job is for publishing content after a branch has been 116merged into the upstream default branch. 117 118QEMU_JOB_AVOCADO 119~~~~~~~~~~~~~~~~ 120 121The job runs the Avocado integration test suite 122 123Contributor controlled runtime variables 124---------------------------------------- 125 126The following variables may be set by contributors to control 127job execution 128 129QEMU_CI 130~~~~~~~ 131 132By default, no pipelines will be created on contributor forks 133in order to preserve CI credits 134 135Set this variable to 1 to create the pipelines, but leave all 136the jobs to be manually started from the UI 137 138Set this variable to 2 to create the pipelines and run all 139the jobs immediately, as was historicaly behaviour 140 141QEMU_CI_AVOCADO_TESTING 142~~~~~~~~~~~~~~~~~~~~~~~ 143By default, tests using the Avocado framework are not run automatically in 144the pipelines (because multiple artifacts have to be downloaded, and if 145these artifacts are not already cached, downloading them make the jobs 146reach the timeout limit). Set this variable to have the tests using the 147Avocado framework run automatically. 148 149Other misc variables 150-------------------- 151 152These variables are primarily to control execution of jobs on 153private runners 154 155AARCH64_RUNNER_AVAILABLE 156~~~~~~~~~~~~~~~~~~~~~~~~ 157If you've got access to an aarch64 host that can be used as a gitlab-CI 158runner, you can set this variable to enable the tests that require this 159kind of host. The runner should be tagged with "aarch64". 160 161AARCH32_RUNNER_AVAILABLE 162~~~~~~~~~~~~~~~~~~~~~~~~ 163If you've got access to an armhf host or an arch64 host that can run 164aarch32 EL0 code to be used as a gitlab-CI runner, you can set this 165variable to enable the tests that require this kind of host. The 166runner should be tagged with "aarch32". 167 168S390X_RUNNER_AVAILABLE 169~~~~~~~~~~~~~~~~~~~~~~ 170If you've got access to an IBM Z host that can be used as a gitlab-CI 171runner, you can set this variable to enable the tests that require this 172kind of host. The runner should be tagged with "s390x". 173 174CENTOS_STREAM_8_x86_64_RUNNER_AVAILABLE 175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 176If you've got access to a CentOS Stream 8 x86_64 host that can be 177used as a gitlab-CI runner, you can set this variable to enable the 178tests that require this kind of host. The runner should be tagged with 179both "centos_stream_8" and "x86_64". 180