CKI pipeline configuration options

All pipelines share the same code and make decisions based on the passed configuration options in form of trigger variables. Other tools interacting with the pipeline may also need to do the same, one such example would be reporter which needs to know where to send emails for the pipeline.

All the options below are in alphabetical order.

Note that this list does not contain internal pipeline variables that are technically possible to be overridden but are not meant to be touched, such as rpmbuild options or ccache related variables.

For variables required by triggers but not needed for the pipeline run itself, please refer to the pipeline triggers documentation.

Pipeline configuration option list

The pipeline and tooling handles both True and true (similarly with False/false). For simplicity, only capitalized values are mentioned below.

• architectures: Space-separated list of architectures to run the pipeline for, in RPM architecture format. Required in every pipeline.

• ARTIFACT_*: Information about where to find original pipeline artifacts if short pipelines are requested via tests_only=true. Used by the CI bot. MUST NOT BE USED IN PRODUCTION.

• AUTOMOTIVE_CONFIGURATION_URL: URL which holds test image related definitions in a json file for automotive testing. Default set to SIG AutoSD

• branch: Target branch of the kernel repository that should be built and tested. Used in reporting and messaging, not in the pipeline itself. commit_hash must be provided for a correct pipeline run.

• brew_task_id: Brew or Koji task ID. Only applicable to Brew/Koji pipelines.

• brew_nvr: Brew or Koji SRPM NVR. This will trigger pipelines similar to brew_task_id, but the resulting KCIDB objects will have IDs based on the GitLab pipeline IDs (i.e. NOT brew-123). Only applicable to Brew/Koji pipelines.

• build_noarch: True if noarch RPMs should be built, False otherwise. Defaults to True. Enabling this without actually building any such RPMs will blow up the build noarch job. Only applicable to kernels built as RPMs.

• build_selftests: True if any kernel selftests should be built, False otherwise. Defaults to False. Will cause make kselftest-merge configuration target to be called. Has to be used together with debug_architectures option (as the selftest config target pulls in debug options). Only applicable to kernels built as tarballs. NOTE selftests build is currently only supported for debug builds on x86_64 architecture, other architectures are skipped.

• builder_image: Container image used for kernel building. Defaults to quay.io/cki/builder-rawhide.

• checkout_contacts: A string representing a JSON-encoded list of emails involved with the KCIDB checkout. Defaults to ‘[]’.

• CKI_DEPLOYMENT_ENVIRONMENT: retrigger if the pipeline is a retrigger for testing and should be ignored by all tooling. Defaults to production.

• commit_hash: Commit to check out from the repository. Required if a kernel needs to be built. For MR child pipelines, this is set to CI_COMMIT_SHA.

• compiler: Which compiler toolchain to use to build the kernel. Can be gcc or clang, defaults to gcc. Specific behavior of clang differs on supported functionality with Fedora configuration for given architecture. Has effect only when a kernel is built.

• source_package_name: Name of the kernel package. Defaults to kernel.

• config_target: make configuration target to use on top of Fedora configuration files. Defaults to olddefconfig. Only applicable to kernels built as tarballs.

• coverage: True to build a kernel with code coverage. Defaults to False.

• coverage_dirs: Space-separated list of kernel source directories to capture coverage data for. Has effect with coverage=True only. Default value is specified in kpet-db repository.

• debug_architectures: Space-separated list of RPM architectures to build and test the debug variant (x86_64, aarch64, ppc64le, s390x, riscv64). Defaults to empty.

• disttag_override: Override for the RPM %dist macro of the builder container image. This is necessary if the built kernel belongs to a different distribution release, e.g. .el8_3 for a RHEL 8.3 kernel built on the builder-rhel container image which has a %dist macro of .el8. Only applicable to kernels built as RPMs.

• domains: A space-separated list of regular expressions fully-matching names or slash-separated paths of kpet “host domains” to restrict test execution to. All tests targeting hosts in the matching domains will be executed once for each of the regular expressions. Run kpet domain tree to see available domains. If empty, tests will be executed once in all domains. Defaults to available.

• download_separate_headers: If true, download separate kernel-headers binary from koji. Defaults to false. Useful if the headers are not part of the base kernel package. Only applicable to Brew/Koji pipelines.

• extra_baseline_run_set_patterns: Space-separated string representing test set patterns of runs to add to the pipeline. Useful if baseline-like runs are needed to be executed on top of targeted testing. Defaults to an empty string, i.e. no extra runs.

• force_baseline: If true, MR pipeline runs won’t run targeted testing but will pretend to be a git branch tip run. Defaults to false.

• git_url: URL of the kernel repository that should be built and tested. Only used when a kernel is built.

• git_url_cache_owner: The file name for the git cache is determined as owner.repo from the git URL. Explicitly set this variable to override the owner component for the git cache used for git_url.

• image_tag: Container tag used for all container images in the pipeline. Defaults to production.

• kcidb_tree_name: KCIDB tree identifier, used e.g. in tree filtering in Data Warehouse. Typically contains upstream subtree name or distribution release, e.g. mainline.kernel.org, rhel-9 or rhel-8.10.

• kernel_config_url: URL to a kernel configuration to use as a base for the built kernel. Optional, defaults to empty string. If not provided, Fedora rawhide configuration files are used.

• kernel_version Version part of the build NVR. Required for Brew/Koji builds. For builds done by CKI, it is determined in the pipeline.

• kpet_extra_components: A regular expression matching kpet’s build “components” to consider included into the kernel being tested, along with automatically-detected ones. See the output of kpet component list for a list and description of recognized components.

• kpet_high_cost: Override for kpet’s --high-cost option. Defaults to triggered. See the output of kpet run generate --help command for possible values.

• kpet_tree_name: For non-RHEL kernels, kpet-db tree name as returned by kpet tree list. For RHEL kernels, should be empty. There, the kpet tree selection script is used to determine the kpet-db tree name from the NVR.

• KPET_ADDITIONAL_VARIABLES: Additional environment variables that should be passed as variables to kpet. Only for pipelines triggered via the CI bot. MUST NOT BE USED IN PRODUCTION.

• make_target: targz-pkg if make targz-pkg should be used for building the kernel, rpm if rpmbuild should be used. Defaults to rpm. NOTE should be renamed to build_target in the future to reflect not all kernels are build using the make command.

• merge_branch: Optional. Name of the branch which should be merged into the tested kernel tree before patch application.

• merge_tree: Optional. Link to the kernel repository that should be merged into the tested kernel tree before patch application. Defaults to git_url.

• mr_id: ID of the merge request that should be tested. Only applicable to kernels living in GitLab.

• mr_source_branch_hash: Source branch HEAD commit if commit_hash points to a merge commit. For MR child pipelines, this is set to CI_MERGE_REQUEST_SOURCE_BRANCH_SHA.

• name: NOTE Deprecated and replaced by kcidb_tree_name.

• native_architectures: Space-separated list of RPM architectures supported by RHEL >= 8 other than x86_64 that should use native compilation (aarch64, s390x, ppc64le, riscv64). This requires native gitlab-runners to be set up for that purpose. Currently, this is only the case for aarch64. Defaults to aarch64.

• native_tools: True if kernel tools should be built separately from kernel on a native architecture. Defaults to False. Only available for kernels built as RPMs which have the required kernel features backported.

• native_tools_architectures: Space-separated list of RPM architectures supported by RHEL >= 8 other than x86_64 that should use native tools compilation (aarch64, s390x, ppc64le, riscv64). This requires native-tools gitlab-runners to be set up for that purpose. Currently, this is only the case for aarch64, s390x and ppc64le. Defaults to aarch64 s390x ppc64le.

• officialbuild: true if the kernel build coming from Brew/Koji and is not a scratch build. Defaults to false. If true, adds officialbuild to components list.

• package_name: Name of the kernel variant, e.g. kernel or kernel-rt. Required for kernels built as RPMs (both ones built in the pipeline and by build systems) as boot test uses the value. Defaults to kernel.

• patch_urls: Links to raw patches or mboxes to apply, in a form of space-separated string. Patches are applied using git am.

• public: true or false. Used by DataWarehouse and KCIDB forwarder to determine whether the kernel build is internal (public=false), or can be shared publicly (public=true). Defaults to false.

• report_rules: JSON encoded list of reporting rules for the current checkout.

• rpmbuild_with: Space-separated strings marking a set of --with options to be added to the rpmbuild command. Only applicable to kernels packaged as RPMs. Defaults to an empty string (no extra options added).

• rt_kernel: True if realtime kernel configuration options should be enabled for tarball packaged kernels. Defaults to False.

• run_redhat_self_test: True if the pipeline should run the kernel’s redhat/self-test testsuite. Defaults to False.

• scratch: true if the kernel build is a scratch build (Brew/Koji) or is triggered by a merge request, false if not. Defaults to true. This is also set to false for git-repo baselines, i.e. pipelines not associated with a merge request.

• selftest_subsets: Optional variable specifying a list of space-separated selftest subsets to build. If it’s missing and build_selftests is True, CKI will build all selftest subsets. Only applicable to kernels packaged as tarballs.

• send_pre_test_notification: True if an email should be sent to a build submitter before testing starts. Defaults to False. The email contains links to Beaker jobs for people to follow, thus is only useful for internal contributors. NOTE After migrating to UPT this notification will make no sense as there will be no test logs available in the Beaker jobs, and thus the option may end up being removed or reworked.

• send_report_to_upstream: True if the email report should be sent to the contributors. Causes the triggers to add emails to the mail_to, mail_cc and mail_bcc trigger variables and the reporter to send the email to them. NOTE recipient handling is being reworked and this variable will be removed later.

• server_url: Value of the --server option of the koji command to use to retrieve builds. Required for Brew/Koji pipelines using download_separate_headers.

• skip_beaker: True if only a dry run for submitting a test job is needed. Defaults to True in CI runs, to False otherwise.

• skip_build: True if the build stage should be skipped in the pipeline. Useful for only running testing with already existing kernels. Defaults to False.

• skip_createrepo: True if the createrepo stage should be skipped in the pipeline. Useful for only running testing with already existing kernels. Defaults to False.

• skip_kernel_installation: True if the kernel installation task (Boot test - kpkginstall) should be skipped. Useful for external provisioner or systems which have a preconfigured kernel already installed. Defaults to False.

• skip_merge: True if the merge stage should be skipped in the pipeline. Useful for only running testing with already existing kernels. Defaults to False.

• skip_publish: True if the publish stage should be skipped in the pipeline. Useful for only running testing with already existing kernels. Defaults to False.

• skip_results: True if result summary and known issue detection should be disabled. Defaults to False.

• skip_setup: True if the setup stage should be skipped. Defaults to False.

• skip_test: True if the test stage should be skipped. Defaults to False.

• srpm_make_target: make target to build SRPM. Defaults to rh-srpm.

• subject: Email subject to use with email reports for the test results, will be prefixed with the result summary. If missing, a generic subject mentioning the kernel version and pipeline name will be built.

• submitter: Email of the build submitter.

• test_priority: Priority for submitting test jobs. Can be low, medium, normal, high or urgent. Defaults to normal. NOTE not every provisioner supports test run priorities. USE RESPONSIBLY.

• test_runner: Where to run testing. Currently available runners are aws (limited testing available in virtual machines), testingfarm and beaker. Defaults to beaker.

• test_set: Test set(s) to run for the pipeline, in the kpet generate -s option syntax. By default, all sets are included for MR runs (and tests are picked via diff analysis) and official kernel builds are limited to sanity kt1 testing. Also check out documentation for targeted testing for builds on how to limit test sets for a single build.

• tests_regex: If specified, tests names have to fullmatch() this regular expression to run. Can be combined with test_set to only run specific tests from the set(s). Not meant for production use as the test names can change, always use test_set for production. Current list of test names can be retrieved by running kpet test list. Some tests are selected based on officialbuild component, see scratch option how to set or unset it.

• test_upt: True if the pipeline is for running UPT smoke tests. Defaults to False, i.e. generate the Beaker XML with kpet.

• top_url: Value of the --topurl option of the koji command to use to retrieve builds. Required for Brew/Koji pipelines using download_separate_headers.

• trigger_job_name: The CI_JOB_NAME which triggered the pipeline. Useful for consumers of downstream pipeline webhook events such as the kernel-webhook’s ckihook. A regular downstream pipeline is expected to be named using the following format: <RHELMAJOR>_<VARIANT>_<TYPE>_<SECLEVEL>:

  • <RHELMAJOR>: RHEL major version, i.e. rhel8 or for CentOS Stream c9s, c10s, etc.
  • <VARIANT>: optional and can be automotive, realtime or realtime[_-]check
  • <TYPE>: baseline or merge[_-]request
  • <SECLEVEL>: optional; only private is a valid value

  There are also special coverage and shadow builds enabled for specific setups. These conform to the schema of <RHELMAJOR>_<VARIANT>_baseline_coverage_build and <CENTOSMAJOR>_<RHELMAJOR>_compat_<TYPE>. Note that the <RHELMAJOR> in case <CENTOSMAJOR> is used as well matches the RHEL name, not the CentOS Stream name.

• upt_smoke_tests: Space-separated list of UPT smoke tests to run. Defaults to all available smoke tests (See pipeline variables). Has effect only if test_upt is True.

• watch_branch Git branch to watch to trigger testing on changes. Defaults to branch. For use with git repo trigger only.

• watch_url: Git repo URL to watch to trigger testing on changes. Defaults to git_url. For use with git repo trigger only.

• web_url: Value of the --weburl option of the koji command to use to retrieve builds. Required for Brew/Koji pipelines using download_separate_headers.