koji-tag-build

Apply a tag to one or more builds

$ koji tag-build [tag] [NVR1 NVR2 ...]

$ koji tag-build [tag] [NVR1 NVR2 ...] --nowait

$ koji tag-build [tag] [NVR1 NVR2 ...] --force

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

koji tag-build [options] <tag> <build> [<build> ...]

<tag>
    The name of the Koji tag to which the build(s) should be associated. This tag must pre-exist in the Koji system and be accessible to the user.

<build>
    The NVR (Name-Version-Release) string or the integer ID of the Koji build to tag. Multiple build arguments can be provided to tag several builds into the same tag simultaneously.

-h, --help
    Show the help message for the command and exit.

--debug
    Enable debug output, providing more verbose information about the command's execution and internal operations.

--quiet
    Suppress standard output, only displaying error messages if they occur during the operation.

--strict
    Apply strict checking. While its primary use is with untag-build to ensure a build is only removed from specified tags, for tag-build it can enforce specific Koji policies or behaviors if configured by the hub.

--user=USER
    Specify the username for explicit authentication with the Koji hub. This is typically used in conjunction with --password if not relying on Kerberos or client certificates for authentication.

--password=PASSWORD
    Provide the password for authentication with the Koji hub. This option should always be used with --user. For enhanced security, using client certificates or Kerberos is generally preferred over plaintext password input.

--url=URL
    Specify an alternative URL for the Koji hub. This overrides the default hub URL configured in the Koji client configuration file or environmental variables.

--config=CONFIG
    Specify an alternative Koji client configuration file to use. This allows overriding the default configuration files located at ~/.koji/config or system-wide paths.

--session=SESSION
    Use a pre-existing Koji session ID for authentication. This bypasses the need for explicit user/password or certificate-based login for the current command execution, reusing an active session.

--skip-check
    Skip some internal checks, such as verifying if the build is already tagged into the specified tag. Use this option with caution, as it can override existing conditions or policy checks without warning, potentially leading to redundant entries or unexpected states.

The koji-tag-build command is a fundamental client-side utility within the Koji build system. Koji is an open-source build system primarily used for RPM package building and management, notably within Fedora, CentOS, and other RPM-based distributions.

This command's primary function is to associate an existing, completed Koji build with one or more specified Koji tags. In Koji, a tag acts as a logical grouping mechanism, often representing a release stream, a development branch, or a specific stage in a software development lifecycle (e.g., 'f39-updates-candidate', 'epel9').

By tagging a build, you make it discoverable and available under that tag. This is crucial for promoting builds from a testing tag to a release tag, or for ensuring that a specific version of a package is included in a particular repository. Builds can belong to multiple tags simultaneously, allowing for flexible management of build states and availability across different contexts. Successful execution of this command requires appropriate permissions on the Koji hub for the target tag.

Using koji-tag-build requires appropriate permissions within the Koji system. Only Koji administrators or users with specific roles (e.g., 'tag' permission on the target tag) can successfully execute this command. Incorrectly tagging builds can lead to unexpected package availability or conflicts within repositories. Be particularly cautious when using the --skip-check option, as it can bypass safeguards designed to prevent duplicate tagging or other policy violations, potentially causing unintended side effects in your Koji environment. Always ensure the specified tag is the correct and intended destination for the build to avoid publishing unintended versions or confusing repository contents.

Here are some common ways to use koji-tag-build:

Tag a single build into a development tag:
koji tag-build f39-candidate mypackage-1.0-1.fc39

Tag multiple builds into a release tag, assuming you have a Koji configuration file set up:
koji tag-build f39-release myotherpackage-2.1-3.fc39 anotherpackage-0.5-1.fc39

Tag a build using its numeric ID instead of NVR:
koji tag-build epel9-testing 1234567

Tag a build and skip checks (use with extreme caution):
koji tag-build --skip-check rawhide newfeature-3.0-1.fc40

The koji-tag-build command is an integral part of the Koji build system, which was originally developed by Red Hat and first released around 2005-2006 to manage the complexities of building and maintaining RPM packages for Fedora and Red Hat Enterprise Linux. As a core function for build promotion and lifecycle management, the ability to tag builds has been present since the early versions of Koji. Its design reflects the need for robust, auditable control over what packages are included in various release stages and repositories, evolving alongside the Koji project to support modern build workflows and distributed development environments.

koji(1), koji-build(1), koji-untag-build(1), koji-list-tags(1), koji-list-builds(1), koji-tag-pkg(1)