The documented process should be updated to reflect the new process once GitLab transitions to it completely and drops the old process involving registration tokens as hinted by the note. Signed-off-by: Erik Skultety <eskultet(a)redhat.com&gt; --- docs/ci-runners.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/ci-runners.rst b/docs/ci-runners.rst index fd5fdd121a..4a93f0e872 100644 --- a/docs/ci-runners.rst +++ b/docs/ci-runners.rst @@ -54,6 +54,16 @@ configurations on the GitLab UI. Navigate to: * *Runners activated for this project*, then * Click on the *Edit* icon (next to the *Lock* Icon) +*Note: GitLab has changed the runner registration process deprecating the use of +registration tokens in future versions, so while the above process is still +applicable (though the settings are now a bit more hidden) at the time of writing +this note (09/2023), GitLab v18.0+ is planned to completely switch to a new +process (see the links below), deleting the use of registration tokens.* + + * https://gitlab.com/gitlab-org/gitlab/-/issues/380872 + * https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html + * https://docs.gitlab.com/ee/ci/runners/runners_scope.html#create-a-shared-... + Don't forget to add a tag to your runner as these are used to route specific jobs to specific runners, e.g. if a job in ``ci/integration.yml`` looked like this :: -- 2.41.0

While we may have needed to run TCK through Avocado by explicitly using the '--tap' option (still possible), we can get a nice output from Avocado by default leaving the option out which is exactly what we do inside GitLab CI environment. Signed-off-by: Erik Skultety <eskultet(a)redhat.com&gt; --- docs/testtck.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/testtck.rst b/docs/testtck.rst index 100a278acd..d7f5483b5f 100644 --- a/docs/testtck.rst +++ b/docs/testtck.rst @@ -78,7 +78,7 @@ as root the test suite as root (when running with Avocado): :: - # avocado --config avocado.config run --tap - ./scripts/ + # avocado --config avocado.config run from the TCK's git root. -- 2.41.0

The fact that we need ci/helper script to run the workloads remains true, but the invocation has changed as of commit eb41e456 . We also extracted GitLab job specs into a standalone ci/jobs.sh script which allows execution of any container job we run in upstream CI locally, unlike the original functionality which only allowed builds, tests and shell (although important to say it could be adjusted with the right meson/ninja args). lcitool also became mandatory as it enables the container execution which replaced a Makefile we used to have for this purpose. Signed-off-by: Erik Skultety <eskultet(a)redhat.com&gt; --- docs/testing.rst | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/testing.rst b/docs/testing.rst index a597c3ed07..9ca47072ba 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -48,11 +48,17 @@ Running container builds with GitLab CI As long as your GitLab account has CI minutes available, pipelines will run automatically on every branch push to your fork. -Running container builds locally -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Running container jobs locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to run container builds locally, we have a ``helper`` script inside -the ``ci`` directory that can pull, build, and test (if applicable) changes on +GitLab CI configuration file is the only source of truth when it comes to +various job specifications we execute as part of the upstream pipeline. +Luckily, all "script" (i.e. Bash scripts) were extracted to standalone Shell +functions in ``ci/jobs.sh``. This allows users to run any of the container +GitLab job specifications locally by just referencing the job name. + +When it comes to actually running the GitLab jobs locally, we have a +``ci/helper`` script can pull, build, and test (if applicable) changes on your current local branch. It supports both the Docker and Podman runtimes with an automatic selection of whichever runtime is configured on your system. In case neither has been enabled/configured, please go through the following @@ -130,12 +136,27 @@ the default libvirt registry: fedora-rawhide-cross-mingw64 ... -Now let's say one would want to build their local libvirt changes on Alpine -Edge using their own GitLab's registry container. They'd then proceed with +Now, let's say one would want to run the ``website`` job from GitLab on Debian +11. This is how a GitLab job specification can be referenced on ``ci/helper``'s +command line: :: - $ ci/helper build --image-prefix registry.gitlab.com/<user>/libvirt/ci- alpine-edge + $ ci/helper run --job website debian-10 + +What if you want to run an rpmbuild of libvirt on an RPM distro? + +:: + + $ ci/helper run --job rpmbuild fedora-38 + +Want to use your own, say alpine-edge, container image from your GitLab +container registry? +Proceed with the following: + +:: + + $ ci/helper run --job build --image-prefix registry.gitlab.com/<user>/libvirt/ci- alpine-edge Finally, it would be nice if one could get an interactive shell inside the test environment to debug potential build issues. This can be achieved with the @@ -143,7 +164,7 @@ following: :: - $ ci/helper shell alpine-edge + $ ci/helper run --job shell alpine-edge Integration tests -- 2.41.0

It's mentioned in an earlier paragraph that Perl bindings in correct version are needed, but there's no note about libvirt even though it should be obvious. So make a clear note on that and while at it, do mention the possibility to get upstream libvirt RPMs from GitLab CI artifacts if users don't feel like building everything on their own. Signed-off-by: Erik Skultety <eskultet(a)redhat.com&gt; --- docs/testtck.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/testtck.rst b/docs/testtck.rst index 89760e3f63..f57af61aa8 100644 --- a/docs/testtck.rst +++ b/docs/testtck.rst @@ -73,6 +73,12 @@ Again, for further details on how to update ``lcitool`` virtual machines, please refer to `Updating VMs with a given project dependencies <https://gitlab.com/libvirt/libvirt-ci/-/blob/master/docs/vms.rst>`__ +Note that lcitool only installs build dependencies, so as mentioned above you'll +need both libvirt **and** libvirt Perl bindings installed in order to be able +to run TCK. You can (depending on use case) either build both inside the VM and +install manually or install the corresponding RPMs from GitLab CI build +artifacts. + We also recommend executing TCK using the Avocado framework as the test harness engine which means that you'll have to install Avocado in the test environment as well. You can get it either from -- 2.41.0