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 successful 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 the historical 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
185CCACHE_DISABLE
186~~~~~~~~~~~~~~
187The jobs are configured to use "ccache" by default since this typically
188reduces compilation time, at the cost of increased storage. If the
189use of "ccache" is suspected to be hurting the overall job execution
190time, setting the "CCACHE_DISABLE=1" env variable to disable it.
191