docs/devel/testing/ci-jobs.rst.inc

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