Fedora’s Koji Build System

Updated

October 30, 2026

Fedora’s Koji Build System

In the RPM ecosystem, Fedora and Red Hat Enterprise Linux rely on Koji—a distributed, declarative build system designed for high concurrency, cryptographic traceability, and multi-architecture targets.

+-----------------------------------------------------------+
|                   Fedora Koji Architecture                |
|                                                           |
| 1. Developer CLI / Web UI: `fedpkg build` / `koji build`  |
|                         |                                 |
|                         v                                 |
| 2. Koji Hub (XML-RPC API daemon + PostgreSQL database)    |
|    - Authenticates maintainers via Kerberos / SSL certs   |
|    - Manages tags, targets, inheritance trees, and tasks  |
|                         |                                 |
|                         v                                 |
| 3. Koji Builders (kojid daemon running on bare metal)     |
|    - Launches `mock` inside isolated chroot               |
|    - Installs minimal buildroot based on target tag       |
|    - Executes `rpmbuild -ba package.spec`                 |
|                         |                                 |
|                         v                                 |
| 4. Tagging & Inheritance System                           |
|    - Tag: `f40-build` -> `f40-updates-candidate` -> `f40` |
+-----------------------------------------------------------+

Tag-Based Inheritance and Promotion

The hallmark of Koji is its tag inheritance model: - Every release has a build tag (e.g., f40-build) that specifies exactly which RPM repository packages are visible to the compiler inside the mock chroot. - When a package finishes building successfully, it is tagged as f40-updates-candidate. - After passing automated openQA integration testing and receiving community karma in Fedora’s Bodhi updates system, an administrator simply moves the tag pointer to f40-updates. - The repository generation tool (createrepo_c) regenerates metadata dynamically based on the current tags in PostgreSQL.

mock: Hermetic RPM Building

At the worker layer, Koji invokes mock: - Creates an isolated chroot using Linux mount namespaces. - Uses dnf to download and unpack a fresh RPM buildroot for each individual build. - Ensures zero contamination between builds on the same physical server.