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 * QEMU_CI_CONTAINER_TAG - the tag used to publish containers 74 in stage 1, for use by build jobs in stage 2. Defaults to 75 'latest', but if running pipelines for different branches 76 concurrently, it should be overridden per pipeline. 77 78 * QEMU_CI_UPSTREAM - gitlab namespace that is considered to be 79 the 'upstream'. This defaults to 'qemu-project'. Contributors 80 may choose to override this if they are modifying rules in 81 base.yml and need to validate how they will operate when in 82 an upstream context, as opposed to their fork context. 83 84 * nnn - other misc variables not falling into the above 85 categories, or using different names for historical reasons 86 and not yet converted. 87 88Maintainer controlled job variables 89----------------------------------- 90 91The following variables may be set when defining a job in the 92CI configuration file. 93 94QEMU_JOB_CIRRUS 95~~~~~~~~~~~~~~~ 96 97The job makes use of Cirrus CI infrastructure, requiring the 98configuration setup for cirrus-run to be present in the repository 99 100QEMU_JOB_OPTIONAL 101~~~~~~~~~~~~~~~~~ 102 103The job is expected to be successful in general, but is not run 104by default due to need to conserve limited CI resources. It is 105available to be started manually by the contributor in the CI 106pipelines UI. 107 108QEMU_JOB_ONLY_FORKS 109~~~~~~~~~~~~~~~~~~~ 110 111The job results are only of interest to contributors prior to 112submitting code. They are not required as part of the gating 113CI pipeline. 114 115QEMU_JOB_SKIPPED 116~~~~~~~~~~~~~~~~ 117 118The job is not reliably successsful in general, so is not 119currently suitable to be run by default. Ideally this should 120be a temporary marker until the problems can be addressed, or 121the job permanently removed. 122 123QEMU_JOB_PUBLISH 124~~~~~~~~~~~~~~~~ 125 126The job is for publishing content after a branch has been 127merged into the upstream default branch. 128 129QEMU_JOB_AVOCADO 130~~~~~~~~~~~~~~~~ 131 132The job runs the Avocado integration test suite 133 134Contributor controlled runtime variables 135---------------------------------------- 136 137The following variables may be set by contributors to control 138job execution 139 140QEMU_CI 141~~~~~~~ 142 143By default, no pipelines will be created on contributor forks 144in order to preserve CI credits 145 146Set this variable to 1 to create the pipelines, but leave all 147the jobs to be manually started from the UI 148 149Set this variable to 2 to create the pipelines and run all 150the jobs immediately, as was historicaly behaviour 151 152QEMU_CI_AVOCADO_TESTING 153~~~~~~~~~~~~~~~~~~~~~~~ 154By default, tests using the Avocado framework are not run automatically in 155the pipelines (because multiple artifacts have to be downloaded, and if 156these artifacts are not already cached, downloading them make the jobs 157reach the timeout limit). Set this variable to have the tests using the 158Avocado framework run automatically. 159 160Other misc variables 161-------------------- 162 163These variables are primarily to control execution of jobs on 164private runners 165 166AARCH64_RUNNER_AVAILABLE 167~~~~~~~~~~~~~~~~~~~~~~~~ 168If you've got access to an aarch64 host that can be used as a gitlab-CI 169runner, you can set this variable to enable the tests that require this 170kind of host. The runner should be tagged with "aarch64". 171 172AARCH32_RUNNER_AVAILABLE 173~~~~~~~~~~~~~~~~~~~~~~~~ 174If you've got access to an armhf host or an arch64 host that can run 175aarch32 EL0 code to be used as a gitlab-CI runner, you can set this 176variable to enable the tests that require this kind of host. The 177runner should be tagged with "aarch32". 178 179S390X_RUNNER_AVAILABLE 180~~~~~~~~~~~~~~~~~~~~~~ 181If you've got access to an IBM Z host that can be used as a gitlab-CI 182runner, you can set this variable to enable the tests that require this 183kind of host. The runner should be tagged with "s390x". 184 185CENTOS_STREAM_8_x86_64_RUNNER_AVAILABLE 186~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 187If you've got access to a CentOS Stream 8 x86_64 host that can be 188used as a gitlab-CI runner, you can set this variable to enable the 189tests that require this kind of host. The runner should be tagged with 190both "centos_stream_8" and "x86_64". 191 192CCACHE_DISABLE 193~~~~~~~~~~~~~~ 194The jobs are configured to use "ccache" by default since this typically 195reduces compilation time, at the cost of increased storage. If the 196use of "ccache" is suspected to be hurting the overall job execution 197time, setting the "CCACHE_DISABLE=1" env variable to disable it. 198