Skip to content

Building in CBS

Koji/CBS buildsystem

CBS permissions


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
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

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.


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 to catch up, as that's the endpoint that 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)
  • 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)

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}


When requesting a new build target via an infra ticket, also request 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>

Now you can submit a build task again your build target by pointing to 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+<pkg_name>.git#<commit_hash>


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

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