Skip to content

Building in CBS

Koji/CBS buildsystem

CBS permissions

Important

Before being able to submit build tasks to koji/cbs, you need to have a valid account and be member of a SIG group ! So be sure you followed all steps described in doc before trying any other step

If you followed the needed steps to get your account and your workstation prepared with needed packages and TLS certs in place, we can proceed with basic validation.

Let's try first to confirm that we can reach CBS/koji and be authenticated (assuming that your username is user :

# cbs hello

g'day, <user>!

You are using the hub at https://cbs.centos.org/kojihub/
Authenticated via client certificate /home/<user>/.centos.cert

Now, if you're member of a SIG group (identified as sig-<groupname> , the following command should list your all your rights and you should see a corresponding build-<groupname> permission : 

# cbs list-permissions --mine
build
livecd
appliance
image
build-<sig_name>
livemedia

As you can see, cbs/koji is using a 1:1 relationship between FAS/ACO group membership (sig-) and the corresponding permissions to submit tasks against specific tags (see below) associated with that SIG.

Note

Just worth knowing that when you're added to a SIG group it can take just some minutes due to replication between FreeIPA servers and fasjson.fedoraproject.org to catch up, as that's the endpoint that cbs.centos.org is using to compute/modify rights. So just keep that in mind and wait for permissions to be returned as shown above before trying anything else

Understanding tags and targets
Koji naming convention

A build target specifies the buildroot and destination of a package for submission. That means that as a user you ask koji to build a package within a specific build environment (build target) that is using a specific buildroot to find dependencies, etc. A Tag is how koji is grouping packages all together, and built packages can be automatically added to a tag after a successfull build, or added manually between other tags with the tag-build koji task.

CBS SIGs tags structure

As you understood, each build target in CBS koji instance will have at least four tags :

  • the -build one (which is where pkg is built and using the configured buildroot)
  • three levels that will be used to promote packages after :
    • candidate (default tag where built packages are tagged to)
    • testing
    • release

Our koji tag structure must follow always the following structure (really for CBS, not the rule for koji but it's important for automation and release to mirror network steps) :

<SIG><CentOS_version>-<Project>-<Version>-{candidate,testing,release} , where:

  • SIG : SIG name , corresponding to IPA group, without the sig- prefix (so sig-cloud would become cloud)
  • CentOS Version: .el version, so el7 means CentOS 7, el8s means CentOS Stream 8, and so on
  • Project : the project that the SIG want to build (example openstack) (see note about images below)
  • Version : project version, can be a number or a string (example yoga for openstack version)
  • repo variant|tag: one of the following : candidate, testing or release (see Delivery about the meaning for these levels)

Note

If you want to create spins (qcow2, container, or else), Project has to be set to images as that's what is used by the sign and push process to see if that's something else then rpm packages/repositories that need to be processed !

Let's use one example, the Cloud SIG would like to build Openstack (Yoga release) for CentOS Stream 9

The build target would be cloud9s-openstack-yoga-el9s and the tags would be : cloud9s-openstack-yoga-{candidate,testing,release}

New build target

To request a new build target, open an infra ticket. Your request should also include the external repositories your target may need to be added (e.g epel, epel-next...).

Submit a build on CBS

Before being able to submit a build task in koji, one has to be the pkg owner for it for all possible tags, so if you want to become the "owner" of a pkg for your own SIG/group, you can proceed like this (and replace ACO_name, pkg_name and basetag with real values) :

for level in candidate testing release ; do
  cbs add-pkg --owner=<ACO_name> <SIG><CentOS_version>-<Project>-<Version>-${level} <pkg_name>
done

Now you can submit a build task again your build target by pointing to git.centos.org URL, pointing to project to build and git commit hash (assuming that you proceeded with needed steps in the git part :

cbs build <SIG><CentOS_version>-<Project>-<Version>-el<CentOS_version> git+https://git.centos.org/rpms/<pkg_name>.git#<commit_hash>

Note

you can always submit a test build by adding --scratch to the build command as argument : that would really build the pkg but wouldn't make it available anywhere to be used. Please avoid using --scratch though as it consumes resources on the build systems for nothing

non rpm artifacts (spins)

There is a way to build something else than rpm packages in koji/cbs, even if that's the primary target (to then create usable repositories of signed packages). Some SIGs want also to build a cloud image/iso image, or container, that contains their packages, and so that can be directly used by end users but you need to create some specific tags (through infra ticket, see below about the images project for your sig)

CBS supports actually this through some plugins, including :

  • kiwi : you need to store some .xml files, following the kiwi naming convention and with a description and then you can call cbs kiwi-build followed by path to your .kiwi file (git+https:// path). Worth knowing that kiwi seems to support cearing container, iso hybrid live image, qcow2 virtual disk image, RootFS, so flexible enough (actually used by Hyperscale SIG)
  • imagefactory : calling cbs with some options like image-build, spin-livecd or spin-livemedia). Not really tested recently though but you can read upstream doc
cbs/koji common error messages
Build already exists

If you want to submit a build and get the following message, it means that same package/version was already built in koji by someone else :

GenericError: Build already exists

As a reminder, each build in koji/cbs needs to be unique and follows the ENVR (Epoch Name Version Release) RPM convention. So if you need an already built package in your tags (built by another SIG), you can also tag-build it to your own tag. (that assumes that you already added the pkg to your tag, per instructions above)

The syntax can be a simple as (pkg_name should be the full rpm package without .rpm at the end): 

cbs tag-build <your_tag-{testing,release,candidate} <pkg_name>-1.0.1.el8
Expired client TLS cert
"Error: [('SSL routines','SSL_shutdown', 'shutdown while in init')]

That means that your ACO cert (obtained with centos-cert) has expired. You can always confirm that with centos-cert -v :

centos-cert -v

[+] 20211222-11:36 centos-cert -> Verifying if TLS cert is still valid ...
[+] 20211222-11:36 centos-cert -> Validating TLS cert against ~/.centos-server-ca.cert ...
/home/<your_username>/.centos.cert: OK
[+] 20211222-11:36 centos-cert -> [SUCCESS] ~/.centos.cert TLS cert verified by ~/.centos-server-ca.cert CA crt
[+] 20211222-11:36 centos-cert -> [SUCCESS] Your TLS cert is still valid for [61] days

If it expired, just use centos-cert as the first time you used it to obtain a new certificate

Promoting packages to mirror network

See dedicated Delivery documentation