From patchwork Thu Jan 23 13:53:34 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Vignesh Raman X-Patchwork-Id: 13948289 Received: from bali.collaboradmins.com (bali.collaboradmins.com [148.251.105.195]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id EC61A21129D; Thu, 23 Jan 2025 13:55:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=148.251.105.195 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1737640528; cv=none; b=t3QbQrYkInNZxUWG8kQlDWeP8E1D/faLOFCgPynEJUX8qENZ3TYphQAb0QxAHQNq0GWO2WUNioA8f491XrkAx28+rOQhZjIpz7WORFNWGukrzld9orvZxtUYYt/LFckjmSOY/qC9Us4tGsUJhVUobtiLhEhlZwndqiyJ7li7Ad0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1737640528; c=relaxed/simple; bh=ch2pzJGTc3aYg+byV9YZ1M2zRb5bhcxs85xaDaa3pgo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=joCBlRNwIUdiNyQ/RTGKNJ/WoIrxV8RhtvAF8wAA5GPLDgRZY8uJvhXZ5jY2XSbzBILPvQFYqpYd0rSHw7JbXShEYv2E+YP0Vq/lLKAHjQCFRw3FNxyuUt/w4X+fBotaXMTO4fQ+f2qaTGJcgCKL3ShNpsnBNNlS2uELhmJvp8A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=collabora.com; spf=pass smtp.mailfrom=collabora.com; dkim=pass (2048-bit key) header.d=collabora.com header.i=@collabora.com header.b=hGfsu1iP; arc=none smtp.client-ip=148.251.105.195 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=collabora.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=collabora.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=collabora.com header.i=@collabora.com header.b="hGfsu1iP" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=collabora.com; s=mail; t=1737640524; bh=ch2pzJGTc3aYg+byV9YZ1M2zRb5bhcxs85xaDaa3pgo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hGfsu1iPsFnFtdsQh8Nj+y4TE6cDO8fezGU99FMQ0bAEMF7kWrcLsL3aoUKmiADB4 llvLPqijmNjuWZ0saz602r5syqW4RONOpdRKDae2HTqqumHaYBjvceH4qHsv00cLjo U9HU4+xgWPHDH6NKQkhCromw1g7oLofzOuaMHfYb6EHovhylpmp2hr2SHoiFNKNU0b iWNPathzX5FFOMM/qi5D8q0ExCAZDTqQALh672JBDiOh3p799UBS8R1p+UsV1U/rS/ In5e9MEKM1AM02C8kn/OMnU2F3zFTsoyDuBe8jBpuozwfTaPjsQmCq/r1o/GCsmO53 2ttkVy+FEiJGQ== Received: from localhost.localdomain (unknown [171.76.86.251]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: vignesh) by bali.collaboradmins.com (Postfix) with ESMTPSA id A2EA017E0FCA; Thu, 23 Jan 2025 14:55:07 +0100 (CET) From: Vignesh Raman To: kernelci@lists.linux.dev Cc: linuxtv-ci@linuxtv.org, dave.pigott@collabora.com, mripard@kernel.org, linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-kselftest@vger.kernel.org, gustavo.padovan@collabora.com, pawiecz@collabora.com, spbnick@gmail.com, tales.aparecida@gmail.com, workflows@vger.kernel.org, skhan@linuxfoundation.org, kunit-dev@googlegroups.com, nfraprado@collabora.com, davidgow@google.com, cocci@inria.fr, Julia.Lawall@inria.fr, laura.nao@collabora.com, kernel@collabora.com, torvalds@linuxfoundation.org, gregkh@linuxfoundation.org, daniels@collabora.com, helen.koike@collabora.com, shreeya.patel@collabora.com, denys.f@collabora.com, nicolas.dufresne@collabora.com, louis.chauvet@bootlin.com, hamohammed.sa@gmail.com, melissa.srw@gmail.com, simona@ffwll.ch, airlied@gmail.com, Tim.Bird@sony.com, laurent.pinchart@ideasonboard.com, broonie@kernel.org, leobras.c@gmail.com, groeck@google.com, rdunlap@infradead.org, geert@linux-m68k.org, michel.daenzer@mailbox.org, sakari.ailus@iki.fi, jarkko@kernel.org Subject: [PATCH v2 4/5] kci-gitlab: Add documentation Date: Thu, 23 Jan 2025 19:23:34 +0530 Message-ID: <20250123135342.1468787-5-vignesh.raman@collabora.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250123135342.1468787-1-vignesh.raman@collabora.com> References: <20250123135342.1468787-1-vignesh.raman@collabora.com> Precedence: bulk X-Mailing-List: linux-kselftest@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 From: Helen Koike Add documentation of kci-gitlab. Signed-off-by: Shreeya Patel Signed-off-by: Vignesh Raman Signed-off-by: Helen Koike --- Documentation/ci/gitlab-ci/gitlab-ci.rst | 471 +++++++++++++++++++++++ Documentation/index.rst | 7 + 2 files changed, 478 insertions(+) create mode 100644 Documentation/ci/gitlab-ci/gitlab-ci.rst diff --git a/Documentation/ci/gitlab-ci/gitlab-ci.rst b/Documentation/ci/gitlab-ci/gitlab-ci.rst new file mode 100644 index 000000000000..940a80006923 --- /dev/null +++ b/Documentation/ci/gitlab-ci/gitlab-ci.rst @@ -0,0 +1,471 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================================= +Automated Testing with kci-gitlab +========================================= + + +This documentation outlines kci-gitlab, a GitLab CI/CD workflow for the +Linux Kernel. kci-gitlab pipeline is specifically designed for kernel testing. +It provides kernel developers with an integrated, efficient, and flexible +testing framework using GitLab's CI/CD capabilities. The workflow is designed +to simplify testing for developers, allowing tests to be run on any branch at +any time, without the need for specific infrastructure. Tests are automatically +triggered on each `git push`, with results displayed in the GitLab UI. + +.. image:: images/the-pipeline.png + :alt: GitLab-CI pipeline for kernel testing + :align: center + +Customizations and extensions of the pipeline are possible through the +scenarios. Scenarios can override existing jobs, change configurations, or +define new jobs and stages. See :ref:`extending-the-ci` section. + +.. note:: If you are unfamiliar with GitLab CI/CD basic concepts, please check + the `official documentation `_. + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + +Setup +----- + +The kci-gitlab pipeline is set up with minimal configuration required. Pushing code to a +GitLab repository automatically triggers the pipeline provided the CI/CD configuration +file path is set as per the instructions given below.. + + .. code-block:: bash + + # Download the Linux kernel source code + git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + # Create a repository on GitLab and add it as a remote + git remote add gitlab https://gitlab.yourinstance.com/your-username/your-repo.git + # In GitlabCI, go to Settings > CI/CD > General pipelines > CI/CD Configuration file + # and add the following path to it :- + tools/ci/gitlab-ci/gitlab-ci.yml + # Push the code to GitLab + git push gitlab + +.. image:: images/pipelines-on-push.png + :alt: Pipeline triggered on push + :align: center + +Troubleshooting +--------------- + +If the pipeline doesn't trigger automatically, check the following: + +1. **Enable CI/CD in Project Settings:** + + - Go to `Settings > General > Visibility, project features, permissions`. + - Under `Repository`, ensure the `CI/CD` toggle is enabled. + +2. **Enable Container Registry:** + + - Still in `Settings`, find the `Container Registry` section. + - Enable the `Container Registry` toggle. + +3. **CI Minutes and Resources:** + + - If you've exhausted CI minutes or other resources on the Free Tier, + consider setting up a local GitLab runner (see below). + +Setting Up a Local GitLab Runner +-------------------------------- + +You can use your own machine as a runner, instead of the shared runners provided +by your GitLab instance. + +1. **Generate a GitLab Runner Token:** + + - Navigate to `Settings > CI/CD > Runners`. + - Expand the `Runners` section and click on "New project runner". + - Choose "Run untagged jobs" and click "Create runner". + - Copy the provided token. + +.. image:: images/new-project-runner.png + :alt: New project runner button + :align: center + +2. **Launch the Runner:** + + - Ensure Docker is installed and your user is added to the Docker group: + + .. code-block:: bash + + sudo usermod -aG docker + + - Log in again to apply the changes. + - Set up the runner: + + .. code-block:: bash + + export GITLAB_RUNNER_TOKEN= + export GITLAB_URL=https://gitlab.yourinstance.com # Use this for instances other than gitlab.com + cd tools/ci/gitlab-ci + ./bootstrap-gitlab-runner.sh + + +Current Pipeline Jobs +--------------------- + +stage: container +^^^^^^^^^^^^^^^^ + +**job: debian/x86_64_build debian/arm64_build** + +This job prepares the container for x86_64 and arm64 architectures that will be +used by subsequent jobs. It starts from a base Debian image, installing necessary +tools for building the kernel and running tests. The resulting image is pushed to +the project registry and cached. If the image already exists in the registry, it +won't be rebuilt. + +To force a rebuild, update the `FDO_DISTRIBUTION_TAG` variable in the +`container.yml` file. + +stage: static-checks +^^^^^^^^^^^^^^^^^^^^ + +**job: checkpatch** + +Runs the `checkpatch.pl` script on the last `$ICI_PATCH_SERIES_SIZE` commits. +This variable is determined by: + +- `ICI_PATCH_SERIES_SIZE=` The number of differing patches between target and + source branches for merge requests; Or +- `ICI_PATCH_SERIES_SIZE=$KCI_PATCH_SERIES_SIZE` if `KCI_PATCH_SERIES_SIZE` is + set (see :ref:`how-to-set-variables` below). + +Defaults to 1 and raises a GitLab warning if unable to identify the number of +commits. + +**job: smatch** + +Checks `.c` files in the last `$ICI_PATCH_SERIES_SIZE` commits. Creates a +job based on architecture and configuration mentioned in the scenario specific +yaml files. +If a smatch database exists (see `job: smatch-db-generate` below), it reuses it. + +stage: build +^^^^^^^^^^^^ + +**job: build:arm32 build:arm64 build:x86_64** + +Compiles the kernel for each architecture and configuration +in `container.yml`. + +Raises a GitLab warning if "warning" is found in the build log. + +.. image:: images/job-matrix.png + :alt: build kernel jobs + :align: center + +**job: build-docs** + +Builds documentation. Creates a job for each documentation type. Not run +automatically; requires manual triggering. + +stage: test +^^^^^^^^^^^ + +**job: test-boot** + +Runs boot tests using virtme to launch a virtual machine and execute +`test-boot.sh` script. + +stage: cache +^^^^^^^^^^^^ + +**job: smatch-db-generate** + +Generates a smatch database for use by the `smatch` job. Not run automatically; +requires manual triggering. + +.. _extending-the-ci: + +Extending the CI - Test Scenarios (KCI_SCENARIO) +------------------------------------------------ + +The kci-gitlab pipeline offers flexibility and adaptability through the use of +scenarios, enhancing the CI/CD process with broad customization options. +Key capabilities include: + +- **Overriding Existing Jobs:** Tailor existing jobs to meet specific needs or + conditions. + +- **Changing Configurations:** Dynamically adapt job settings to suit various + environments or subsystem requirements. + +- **Defining New Jobs and Stages:** Introduce new jobs and stages for additional + tests, build processes, or deployment strategies. + +These features are particularly useful when a subsystem has distinct +requirements. For instance, to enable testing different configurations for a +specific architecture, running static checks with varied arguments, or +installing specialized tools to conduct targeted tests. + +Writing a test scenario +^^^^^^^^^^^^^^^^^^^^^^^ + +The kci-gitlab pipeline configuration allows the inclusion of additional `.yml` files +based on the `KCI_SCENARIO` variable. For example, setting `KCI_SCENARIO` to `my-scenario` +includes `my-scenario.yml` from the `scenarios//` folder. + +A different container image can be built for the newly added scenario by modifying +the FDO_DISTRIBUTION_TAG. FDO_DISTRIBUTION_EXEC can be used to run scripts to install +the required tools for the container. To illustrate, building a container for a specific +architecture with a custom configuration can be achieved by overriding the `build` job +in the `scenarios//my-scenario.yml` file: + +.. code-block:: yaml + + variables: + FDO_DISTRIBUTION_TAG: "" + FDO_DISTRIBUTION_EXEC: