Notes and miscellaneous details about Koji
This document is intended to illuminate some of the small quirks that you may encounter while running your own koji server.
Koji CLI
Getting Help
- There are multiple ways to receive help from the koji command, each of them gives you something a little different:
- List of user commands:
koji help
- Command-specific help:
koji [command] --help
- List of admin commands:
koji help --admin
- List of user commands:
Building from SRPM
Koji only allows admins access to build directly from srpm. It expects normal users to build out of an SCM.
Building from SCM
SCM Layout
When building out of an SCM, Koji expects there will be a Makefile in the project root that has a 'sources' target. Koji will call 'make sources' on the checked out files.
This target simply needs to download all the sources for the SRPM that are not already included in the SCM repository.
SCM URI Structure
In Fedora, this detail is typically handled by the Makefile.common. Outside of Fedora, you may need to know how to manually submit builds from an SCM to koji.
Koji accepts an SCM URI in this format:
koji build [tag] [scheme]://[user]@[hostname]/[path/to/repository]?[path/to/project]#[revision]
Note the division between repository path and project path. During setup of kojid, the allowed_scms parameter is configured in /etc/kojid/kojid.conf. This value of this parameter should match the path to the repository.
In some SCM configurations, there isn't a difference between repository path and project path. In these cases, it should be understood that dividing your SCM path into two components, URI path and URI query, can seem somewhat arbitrary. An easy way to remember this detail is that the path specified in allowed_scms is the portion of your SCM path that goes before the URI query, any sub-directories not specified in allowed_scms is given to koji as the URI query.
Koji tasks
BuildNotifications
- Koji sends build notifications to the package owner and the user who submitted the build. For BuildNotifications to work successfully, the package owner's username needs to match a valid username for an e-mail address, because kojihub sends to username@domain_in_kojihub.conf.
- For SSL authentication, this means that your CN must be valid as the user portion of an e-mail address.
Koji server administration
Importing an rpm without srpm
If you are running a private koji instance, you may run into a situation where you need to integrate a proprietary rpm into your build system. To do this, it is similar to the package imports you did when bootstrapping your koji instance:
koji import --create-build [package]
Multi-arch builds
There are some packages that need to build across multiple arches. For example, the kernel package no longer builds an i386 kernel, kernels are built on i586 and above. To instruct koji to build these additional arches, use this command:
koji set-pkg-arches [options] <arches> <tag> <package> [<package2> ...]
Note: <arches> is a single entity, so denote multiple arches within quotes (e.g. 'i386 i586 i686').
Manually submitting a task
Occasionally, you may need to manually submit a task to koji. One likely usage is to manually trigger a createRepo. To do this, use this command:
koji make-task [options] <arg1> [<arg2>...]
The make-task command is a bit of under-documented black magic. Task parameters are defined in kojihub.py. The easiest way I have found to figure out the right incantations for make-task is to query the tasks table in the koji database directly. Find a similar task to the one you want to create, and look in the request field for the parameters the task used, and mimic those.
So, citing the createRepo case above, here is an example:
kojiadmin@localhost$ koji make-task --channel=createrepo --priority=15 \ newRepo dist-foo-build
Managing your tags
Occasionally an unwanted package or version of a package will be built by koji. Don't fret. There are two mechanisms to handle rescinding a package or specific package version.
- To remove a specific version of a package, you can untag it:
koji untag-pkg [options] <tag> <pkg> [<pkg>...]
<pkg> supports either %name or %name-%version-%release
- To remove all versions of a package, you can untag it as above or you can administratively block it from being listed in a tag:
koji block-pkg [options] tag package [package2 ...]
Spec file processing
Macro processing
Macros in the spec file are expanded before Requires and BuildRequires are processed. If there are any custom macros in the spec file, the package that drops those macros into /etc/rpm must be tagged under your dist-build tag
%dist tags
For packages that incorporate the %dist tags in their filename, they expect %dist to be defined in /etc/rpm/macros.dist, which was added in Fedora 7. For building on RHEL5/FC6 and earlier, koji needs the [buildsys-macros] package tagged under the dist-build tag.