# Koji/CBS buildsystem

## CBS permissions

!!! important
    Before being able to submit build tasks to koji/cbs, you need to have a valid [account](auth.md) and be member of a SIG group ! So be sure you followed all steps described in [doc](auth.md) 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-<groupname>) 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](https://pagure.io/centos-infra/issues).
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](git.md) 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](http://osinside.github.io/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](https://docs.pagure.org/koji/image_build/)

### 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](delivery.md) documentation