From: Marek Marczykowski-Górecki Date: Wed, 19 Feb 2025 02:56:55 +0000 (+0100) Subject: docs: add basic CI documentation X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=274effbec245732e910d41f61a43dc07bc3e77ce;p=people%2Fandrewcoop%2Fxen.git docs: add basic CI documentation Include info how to get access/enable hardware runners and how to select individual jobs. Signed-off-by: Marek Marczykowski-Górecki Reviewed-by: Stefano Stabellini --- diff --git a/docs/index.rst b/docs/index.rst index 1bb8d02ea3..bd87d736b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,6 +51,7 @@ kind of development environment. :maxdepth: 2 hypervisor-guide/index + misc/ci Unsorted documents diff --git a/docs/misc/ci.rst b/docs/misc/ci.rst new file mode 100644 index 0000000000..7aee55c5d2 --- /dev/null +++ b/docs/misc/ci.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Continuous Integration +====================== + +Xen Project uses Gitlab-CI for automated testing. Test pipelines for official +staging branches are at +``_. Developers can +schedule test pipelines in their repositories under +``_. + +Hardware runners +**************** + +Some of the tests are using dedicated hardware runners. Those are not available freely, but the access is granted to individual developers. To get access to them, ask on the ``#XenDevel:matrix.org`` Matrix channel. +After getting access to relevant runners, few extra changes are necessary in settings of the relevant "xen" gitlab project (under your ``_ namespace): + +1. Go to Settings -> CI/CD, expand the "Runners" section and enable relevant runners for your project. +2. Expand "Variables" section and add ``QUBES_JOBS=true`` variable for Qubes runners. +3. Go to Settings -> Repository, expand "Branch rules" section and add a rule for protected branches - only those branches will get tests on the hardware runners. It's okay to use a pattern for branch name, and it's okay to allow force push. + +Selecting individual tests +************************** + +Normally, all build and test jobs are scheduled in a pipeline. When working on a specific patches, it is sometimes useful to run only jobs relevant for the current work - both to save time and to save CI resources. This can be done by seeting ``SELECTED_JOBS_ONLY`` variable when starting the pipeline. The variable holds a regular expression, enclosed with ``/`` that matches jobs to be included. The variable can be set via the gitlab.com web UI or directly when pushing changes to gitlab:: + + git push -o ci.variable=SELECTED_JOBS_ONLY="/job1|job2/" + +Note if a test job requires some build job, both need to be included in the regex. For example, ``adl-smoke-x86-64-gcc-debug`` requires ``alpine-3.18-gcc-debug``, so to run just this test the command will look like this:: + + git push -o ci.variable=SELECTED_JOBS_ONLY="/adl-smoke-x86-64-gcc-debug|alpine-3.18-gcc-debug/" + +More details at ``_. + +Alternatively, irrelevant jobs can be removed from respective yaml files in ``automation/gitlab-ci`` by adding temporary commit on top of the branch.