Permission system

Permissions are used by Koji to control access in a number of ways. Some permissions are built-in (e.g. admin, repo), but new ones can be created by administrators.

The admin permission is special. It grants superuser access and can stand in for any other permission.

Most of the built-in permissions control access to various hub calls. For example, the dist-repo permission allows access to create dist repos.

Custom permissions can used as the required permission for a tag, or they can be referenced in hub policies. Note, that you need to first understand the policy mechanism as most permissions are reflected in policy rules.

Any user can be part of user group. User group permissions are inherited by the user.

Permission management

Granting or removing permissions requires the admin permission. A user with sufficient access can use the following koji CLI commands:

koji grant-permission [--new] <permission> <user> [<user> ...]

Grants permission to one or more users. It can be also used to create a new permission with the --new option.

koji revoke-permission <permission> <user> [<user> ...]

Removes the named permission from users.

koji list-permissions [--user <user>] [--mine]

Lists permissions in the system.

Built-in permissions


The following permissions govern access to key administrative actions.


This is a superuser access without any limitations, so grant with caution. Users with admin effectively have every other permission. We recommend granting the smallest effective permission.


Restricted admin permission for handling host-related management tasks.


Permission for adding/deleting/editing tags. Allows use of the tagBuildBypass and untagBuildBypass API calls also. Note, that this name could be confusing as it is not related to tagging builds but to editing tags themselves. Tagging builds (and adding/removing packages from package lists for given tags) is handled by tag and package_list policies respectively.


Permission for adding/deleting/editing targets


The following permissions grant access to trigger specialized tasks.


appliance tasks (koji spin-appliance)


distRepo tasks (koji dist-repo)


image tasks (koji image-build)


livecd tasks (koji spin-livecd)


livemedia tasks (koji spin-livemedia)


This permission grants access to regenerate repos (i.e. to trigger newRepo tasks).


The default vm policy requires this permission to trigger Windows builds.

Data Import

The following import permissions allow a user to directly import build artifacts of different types. We recommend caution when granting these. In general, it is better to use the content generator interface rather than the direct import calls these govern.


used for importing external maven artifacts (koji import-archive --type maven)


used for importing external maven artifacts (koji import-archive --type maven)


used for importing external maven artifacts (koji import-archive --type win)


These remaining permissions don’t fit into other categories.


Defined in the database but currently unused


This special permission is only intended to be granted to the user that kojira runs as. It grants access to regenerate and expire repos, as well as flag them as deleted or broken. Do not grant this permission to normal users. The regen-repo permission can be used to grant access for regeneration only.


This permission grants access to add signatures to rpms and to write out signed copies (koji import-sig and koji write-signed-rpm).