]>
Commit | Line | Data |
---|---|---|
7266ecce AB |
1 | .. _ci_var: |
2 | ||
1ff4f90a DB |
3 | Custom CI/CD variables |
4 | ====================== | |
5 | ||
6 | QEMU CI pipelines can be tuned by setting some CI environment variables. | |
7 | ||
8 | Set variable globally in the user's CI namespace | |
9 | ------------------------------------------------ | |
10 | ||
11 | Variables can be set globally in the user's CI namespace setting. | |
12 | ||
13 | For 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 | ||
17 | Set variable manually when pushing a branch or tag to the user's repository | |
18 | --------------------------------------------------------------------------- | |
19 | ||
20 | Variables can be set manually when pushing a branch or tag, using | |
21 | git-push command line arguments. | |
22 | ||
23 | Example 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 | ||
29 | For 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 | ||
28357dc5 DB |
33 | Setting aliases in your git config |
34 | ---------------------------------- | |
35 | ||
36 | You can use aliases to make it easier to push branches with different | |
37 | CI 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 | ||
44 | Which lets you run: | |
45 | ||
46 | .. code:: | |
47 | ||
48 | git push-ci | |
49 | ||
50 | to create the pipeline, or: | |
51 | ||
52 | .. code:: | |
53 | ||
54 | git push-ci-now | |
55 | ||
56 | to create and run the pipeline | |
57 | ||
58 | ||
6a0e7ea7 DB |
59 | Variable naming and grouping |
60 | ---------------------------- | |
61 | ||
62 | The variables used by QEMU's CI configuration are grouped together | |
63 | in 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 | ||
77 | Maintainer controlled job variables | |
78 | ----------------------------------- | |
79 | ||
80 | The following variables may be set when defining a job in the | |
81 | CI configuration file. | |
82 | ||
00125414 DB |
83 | QEMU_JOB_CIRRUS |
84 | ~~~~~~~~~~~~~~~ | |
85 | ||
86 | The job makes use of Cirrus CI infrastructure, requiring the | |
87 | configuration setup for cirrus-run to be present in the repository | |
88 | ||
89 | QEMU_JOB_OPTIONAL | |
90 | ~~~~~~~~~~~~~~~~~ | |
91 | ||
92 | The job is expected to be successful in general, but is not run | |
93 | by default due to need to conserve limited CI resources. It is | |
94 | available to be started manually by the contributor in the CI | |
95 | pipelines UI. | |
96 | ||
16fee101 DB |
97 | QEMU_JOB_ONLY_FORKS |
98 | ~~~~~~~~~~~~~~~~~~~ | |
99 | ||
100 | The job results are only of interest to contributors prior to | |
101 | submitting code. They are not required as part of the gating | |
102 | CI pipeline. | |
103 | ||
e312d1fd DB |
104 | QEMU_JOB_SKIPPED |
105 | ~~~~~~~~~~~~~~~~ | |
106 | ||
107 | The job is not reliably successsful in general, so is not | |
108 | currently suitable to be run by default. Ideally this should | |
109 | be a temporary marker until the problems can be addressed, or | |
110 | the job permanently removed. | |
111 | ||
112 | QEMU_JOB_PUBLISH | |
113 | ~~~~~~~~~~~~~~~~ | |
114 | ||
115 | The job is for publishing content after a branch has been | |
116 | merged into the upstream default branch. | |
117 | ||
118 | QEMU_JOB_AVOCADO | |
119 | ~~~~~~~~~~~~~~~~ | |
120 | ||
121 | The job runs the Avocado integration test suite | |
122 | ||
6a0e7ea7 DB |
123 | Contributor controlled runtime variables |
124 | ---------------------------------------- | |
125 | ||
126 | The following variables may be set by contributors to control | |
127 | job execution | |
1ff4f90a | 128 | |
28357dc5 DB |
129 | QEMU_CI |
130 | ~~~~~~~ | |
131 | ||
132 | By default, no pipelines will be created on contributor forks | |
133 | in order to preserve CI credits | |
134 | ||
135 | Set this variable to 1 to create the pipelines, but leave all | |
136 | the jobs to be manually started from the UI | |
137 | ||
138 | Set this variable to 2 to create the pipelines and run all | |
139 | the jobs immediately, as was historicaly behaviour | |
140 | ||
1ff4f90a DB |
141 | QEMU_CI_AVOCADO_TESTING |
142 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
143 | By default, tests using the Avocado framework are not run automatically in | |
144 | the pipelines (because multiple artifacts have to be downloaded, and if | |
145 | these artifacts are not already cached, downloading them make the jobs | |
146 | reach the timeout limit). Set this variable to have the tests using the | |
147 | Avocado framework run automatically. | |
148 | ||
6a0e7ea7 DB |
149 | Other misc variables |
150 | -------------------- | |
151 | ||
152 | These variables are primarily to control execution of jobs on | |
153 | private runners | |
154 | ||
40e916b4 TH |
155 | AARCH64_RUNNER_AVAILABLE |
156 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
157 | If you've got access to an aarch64 host that can be used as a gitlab-CI | |
158 | runner, you can set this variable to enable the tests that require this | |
159 | kind of host. The runner should be tagged with "aarch64". | |
160 | ||
cc44a160 AB |
161 | AARCH32_RUNNER_AVAILABLE |
162 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
163 | If you've got access to an armhf host or an arch64 host that can run | |
164 | aarch32 EL0 code to be used as a gitlab-CI runner, you can set this | |
165 | variable to enable the tests that require this kind of host. The | |
166 | runner should be tagged with "aarch32". | |
167 | ||
40e916b4 TH |
168 | S390X_RUNNER_AVAILABLE |
169 | ~~~~~~~~~~~~~~~~~~~~~~ | |
170 | If you've got access to an IBM Z host that can be used as a gitlab-CI | |
171 | runner, you can set this variable to enable the tests that require this | |
172 | kind of host. The runner should be tagged with "s390x". | |
d7c2e2b3 CR |
173 | |
174 | CENTOS_STREAM_8_x86_64_RUNNER_AVAILABLE | |
175 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
176 | If you've got access to a CentOS Stream 8 x86_64 host that can be | |
177 | used as a gitlab-CI runner, you can set this variable to enable the | |
178 | tests that require this kind of host. The runner should be tagged with | |
179 | both "centos_stream_8" and "x86_64". |