koji-build

Build a package from src.rpm

$ koji build [target] [path/to/src.rpm]

$ koji build [target] [git+https://src.fedoraproject.org/rpms/vim.git#e847a50297a216229050bf4db3d06a139104e7cf]

$ koji build [target] [path/to/src.rpm] --scratch

$ koji build [target] [path/to/src.rpm] --wait

$ koji build [target] [path/to/src.rpm] --nowait

$ koji build [[-h|--help]]

koji build <build-target> <source> [options]

Where:
<build-target> specifies the Koji tag/target for the build.
<source> can be an SRPM file path, an URL to an SRPM, or a Git repository URL (e.g., git+https://example.com/repo#branch=master&committish=HEAD&path=foo.spec).

--scratch
    Performs a temporary "scratch" build that is not permanently tagged or saved in Koji's official records. Ideal for testing.

--wait
    Blocks the command execution until the submitted build task has completed, failed, or been canceled.

--nowait
    (Default) Submits the build task to Koji and immediately exits without waiting for completion.

--arch <arch>
    Specifies a comma-separated list of architectures on which to build. If not specified, Koji builds for all architectures defined by the target.

--skip-tag
    Prevents the resulting build from being automatically tagged into the specified <build-target> upon successful completion.

--rebuild
    Forces a rebuild of a package even if a build for the same NVR (Name-Version-Release) already exists in Koji.

--force
    Similar to --rebuild, but may also bypass other checks that prevent duplicate or unnecessary builds.

--build-id <id>
    Assigns a specific build ID to the Koji build task.

--signing-env <env>
    Specifies the signing environment to be used for signing the resulting RPMs.

--message <msg>
    Adds a custom message or note to the build task, visible in Koji logs.

--background
    Runs the build in the background, similar to --nowait, but explicitly states the intent.

--priority <level>
    Sets the priority of the build task in the Koji queue (e.g., 0 for default, higher numbers for higher priority).

--request
    Requests a build for an existing package/NVR, typically used in specific Koji workflows.

--fail-fast
    Causes the build to fail immediately if any part of the build process encounters an error, without attempting subsequent steps.

--no-clean
    Retains the build root on the build host after a failed build, useful for debugging.

--release <string>
    Overrides the release string typically derived from the spec file.

--token <token>
    Provides an authentication token for Koji, useful for automation without password prompts.

--config <file>
    Specifies an alternative Koji configuration file to use.

koji-build is a command-line utility used to initiate builds within the Koji build system, a distributed and trusted build environment primarily used for RPM-based Linux distributions like Fedora and RHEL.

It enables developers and release engineers to submit source RPMs (SRPMs) or source Git repositories to the Koji hub, which then orchestrates the build process on various build hosts. The command ensures that packages are built consistently within defined build roots, using specific compilers, libraries, and build tools, producing official binary RPMs. It supports both permanent, tagged builds and temporary "scratch" builds for testing purposes, making it an essential tool for maintaining the integrity and reproducibility of software packages in large-scale projects.

Requires proper Koji client configuration and authentication credentials to connect to the Koji hub.
Builds consume significant resources on build hosts; excessive or unoptimized builds can impact system performance.
Understanding Koji build targets, tags, and inheritance is crucial for correct package management and release processes.
Scratch builds are not archived long-term and do not contribute to official package releases.

Koji uses "build targets" to define the environment and destination for a build. A target typically corresponds to a Koji tag, which acts as a collection point for successful builds. Packages built against a specific target are usually automatically tagged into it, making them available for further processes like composing repositories or creating distributions. Tags can inherit packages from other tags, forming complex release hierarchies.

The <source> argument for koji-build is versatile. While often an SRPM file, it increasingly supports Git repository URLs, allowing Koji to checkout source code directly from a specified branch, commit, or tag, and then extract the spec file and source tarballs to initiate a build. This Git integration streamlines development workflows and ensures that builds are tied directly to specific points in a version control history.

Koji was developed by Red Hat as a robust, scalable, and secure build system to replace older, less automated methods for building RPM packages for Fedora and later RHEL. Its development started in the early 2000s, driven by the need for a standardized, auditable, and distributed build infrastructure for a large open-source project. The koji-build command is central to its operation, providing the primary interface for users to submit build requests to this system, ensuring consistency and reproducibility across vast numbers of packages and architectures.

koji(1), koji-tag(1), koji-list-builds(1), rpmbuild(8), git(1)