Koji (build system)

Koji (build system)
Name	Koji
Developer	Red Hat
Released	2005
Programming language	Python, JavaScript
Operating system	Linux
License	GNU General Public License

Koji (build system) is a distributed build system designed to automate source-to-binary compilation for Linux distributions and large software projects. It orchestrates build tasks across brokered workers, manages build artifacts, and integrates with package signing, repository management, and continuous integration pipelines. Koji has been used extensively in the Fedora Project and by organizations requiring reproducible builds and complex dependency management.

Overview

Koji provides a centralized build hub that schedules builds, collects metadata, and stores artifacts for later distribution. It is often deployed alongside Fedora Project, Red Hat Enterprise Linux, and other Linux distributions that require coordinated package builds. Koji interacts with systems such as RPM Package Manager, Pungi (tool), Copr (Fedora) and Bodhi (software) to streamline release engineering. Projects like CentOS, Scientific Linux, and corporate infrastructures use Koji to manage multi-architecture builds, and it complements services such as KojiHub-style mirrors and Content Delivery Network deployments.

Architecture and Components

Koji's architecture separates responsibilities across a build hub, web interfaces, and distributed builders. The central components include the Koji hub, which runs a database and API; the task broker, which queues build tasks; and builder machines that perform compilation using tools like mock (tool) and rpm-build. The system integrates with MASH for compose management and uses Pungi (tool) for creating installation ISOs. Koji also integrates with signing services such as GnuPG and interacts with package metadata formats like SRPM and RPM (file format). Administrators commonly deploy Koji with orchestration tools such as Ansible, Puppet, or SaltStack and monitor builds using Prometheus, Grafana, and logging systems like Elastic Stack.

Build Process and Workflows

A typical Koji workflow begins with submitting a source package, often a SRPM or tarball tied to a Git commit or GitLab/GitHub pull request. The hub schedules tasks via the broker, which dispatches them to builders running environments managed by mock (tool), systemd-nspawn, or chroot. Builds produce artifacts referenced by Koji metadata and are deposited in the content store; subsequent tasks can perform signing with GnuPG and push to repositories managed by Pulp (software) or synced to mirrors like MirrorManager. Continuous integration systems such as Jenkins, Zuul (software) and GitLab CI/CD often trigger Koji builds, and release pipelines use tools like Bodhi (software) and KojiWeb to promote builds across channels. Koji supports tagging, inheritance, and permalinks to control which builds are considered for compose and release.

Security and Isolation

Security in Koji centers on isolating untrusted build inputs from sensitive signing keys and infrastructure. Builders are typically sandboxed using systemd-nspawn, container technology, Linux Containers, or virtualization with KVM to mitigate supply chain risks. Access control integrates with authentication systems like LDAP, Kerberos, and OAuth 2.0 providers; role-based permissions enforce actions for accounts tied to organizations such as Red Hat and projects like Fedora Project. Artifact provenance and reproducible build features align with initiatives like Reproducible Builds and software supply chain security practices advocated in standards such as OpenSSF. Secure deployment also leverages monitoring by OSSEC and vulnerability scanning with OpenSCAP.

Integration and Tooling

Koji exposes APIs and command-line tools that integrate with a wide ecosystem. Developers use clients written in Python and web dashboards built with JavaScript frameworks to query build status and download artifacts. Integration points include version control systems like GitHub, GitLab, and Pagure, CI systems such as Jenkins and GitLab CI/CD, and repository managers like Pulp (software) and Spacewalk. Packaging toolchains involving rpm-build, mock (tool), and linters such as rpmlint integrate to validate and create packages. Deployment automation often uses Ansible playbooks and containers orchestrated by Kubernetes for scalable builder fleets.

History and Development

Koji was originally developed to meet the needs of the Fedora Project's build infrastructure and has evolved through contributions from Red Hat engineers, Fedora contributors, and community maintainers. Early design work paralleled build systems used by projects like Debian and OpenSUSE, while later integrations addressed containerized builds and cloud-native deployment patterns influenced by Docker (software) and Kubernetes. Over time, Koji incorporated features for reproducibility and provenance consistent with efforts from Reproducible Builds and security initiatives such as OpenSSF. The project has seen enhancements driven by corporate users including IBM and collaborations with upstream communities like CentOS Stream.

Adoption and Use Cases

Koji is adopted by distributions and organizations that require automated, reproducible package builds across architectures. Notable adopters include Fedora Project, Red Hat Enterprise Linux, CentOS, and research institutions that maintain custom package repositories. Use cases span release engineering for Linux distributions, continuous delivery workflows for enterprise software stacks, and academic projects needing controlled build environments for reproducible research. Ecosystem projects like Copr (Fedora), Bodhi (software), and Pungi (tool) commonly rely on Koji for compiling and promoting builds through lifecycle stages.

Category:Free software Category:Linux build tools