pkgctl-repo

Clone a package repository (requires setting an SSH key in your Arch Linux GitLab account)

$ pkgctl repo clone [pkgname]

$ pkgctl repo clone --protocol https [pkgname]

$ pkgctl repo create [pkgbase]

$ pkgctl repo switch [version] [pkgbase]

$ pkgctl repo web [pkgbase]

pkgctl repo <command> [OPTIONS] [ARGUMENTS]

add --name NAME --baseurl URL [OPTIONS]
    Adds a new RPM repository definition. Requires a unique name and either a base URL, mirror list, or metalink. Other options can define its properties like GPG keys, priority, and initial enabled state.

remove --name NAME
    Removes an existing RPM repository definition by its unique name.

list
    Lists all currently configured RPM repositories managed by pkgctl-repo, along with their key properties.

enable --name NAME
    Enables a previously added or disabled repository, making it available for rpm-ostree operations.

disable --name NAME
    Disables an active repository, preventing rpm-ostree from using it for package layering.

--name NAME
    Specifies the unique name for the repository. This name is used to identify the repository in subsequent commands like remove, enable, or disable.

--baseurl URL
    Defines the base URL for the repository. This option is mutually exclusive with --mirrorlist and --metalink.

--gpgkey PATH|URL
    Specifies the path or URL to the GPG public key used for verifying package signatures from this repository. Essential for secure package layering.

--priority PRIORITY
    Sets the priority for the repository (an integer from 1 to 99). Lower numbers indicate higher priority, influencing package resolution by rpm-ostree/DNF.

--cost COST
    Sets the cost for the repository, influencing package selection when multiple repositories provide the same package.

--description DESCRIPTION
    Provides a human-readable description for the repository, useful for documentation and clarity.

--enabled {true|false}
    Sets the initial enabled state of the repository when adding it. Defaults to true if not specified for add.

--disable-gpg-check
    Disables GPG signature checking for the repository. Use with extreme caution as it compromises security by allowing installation of unsigned packages.

--mirrorlist URL
    Specifies a URL to a mirror list file for the repository. Mutually exclusive with --baseurl and --metalink.

--metalink URL
    Specifies a URL to a metalink file for the repository. Mutually exclusive with --baseurl and --mirrorlist.

pkgctl-repo is a subcommand of the pkgctl utility, designed for managing custom DNF/RPM repositories on systems that leverage rpm-ostree, such as Fedora CoreOS or CentOS Stream CoreOS. It provides a streamlined interface for administrators to add, remove, enable, disable, and list repositories.

These repositories are then utilized by rpm-ostree for layering additional RPM packages on top of the immutable base operating system image. This capability is vital for environments that require specific software or dependencies not included in the default CoreOS image, offering flexibility without compromising the atomic update model of rpm-ostree. The command handles the underlying creation and management of the necessary .repo files.

pkgctl-repo is primarily designed for immutable operating systems like Fedora CoreOS and CentOS Stream CoreOS, which utilize rpm-ostree for package management. Changes made via pkgctl-repo define repositories that rpm-ostree will use for layering. For these changes to take full effect (e.g., after adding new packages from a new repo), an rpm-ostree rebase or apply operation followed by a system reboot is typically required.

Direct use of dnf commands on the host might not always leverage these configured repositories for base system package operations, as rpm-ostree manages the overall system image atomically.

The repositories configured with pkgctl-repo are consumed by rpm-ostree when performing operations like rpm-ostree install or rpm-ostree override replace. They enable rpm-ostree to resolve and layer packages from custom sources on top of the base OS image. This process ensures that layered packages are part of the atomic updates, maintaining system consistency and rollback capabilities.

Unlike temporary DNF configurations, the repository definitions created by pkgctl-repo are persistent across system reboots and updates. They are stored in a manner that rpm-ostree can consistently access them, ensuring that the custom software environment remains stable across OS lifecycle events.

pkgctl-repo emerged as a crucial component of the pkgctl utility, developed to streamline the process of managing external RPM repositories within the unique architectural constraints of rpm-ostree-based systems. Before pkgctl, adding custom repositories often involved manual manipulation of .repo files, which could be cumbersome and error-prone in an immutable OS environment. Its development directly addresses the need for a user-friendly and persistent mechanism to integrate custom software sources into CoreOS distributions, facilitating package layering while adhering to the atomic update model.

pkgctl(1), rpm-ostree(1), dnf.conf(5)