Chapter 6. Managing repositories

6.1. Image Builder default system repositories

The osbuild-composer backend does not inherit the system repositories located in the /etc/yum.repos.d/ directory. Instead, it has its own set of official repositories defined in the /usr/share/osbuild-composer/repositories directory. To override the official repositories, you must define overrides in /etc/osbuild-composer/repositories. This directory is for user defined overrides and the files located here take precedence over those in the /usr directory.

The configuration files are not in the usual YUM repository format known from the files in /etc/yum.repos.d/. Instead, they are simple JSON files.

6.2. Overriding a system repository

You can configure a repository override in the /etc/osbuild-composer/repositories directory by following these steps. NOTE: Prior to RHEL 8.5 release, the name of the repository overrides is rhel-8.json. Starting from RHEL 8.5, the names also respect the minor version: rhel-84.json, rhel-85.json, and so on. .Prerequisites

  • You have a custom repository that is accessible from the host system


  1. Create a directory that contains the repository overrides you want to use:

    $ sudo mkdir -p /etc/osbuild-composer/repositories
  2. Create a JSON file with the following structure, for example:

        "<ARCH>": [
                "name": "baseos",
                "metalink": "",
                "baseurl": "",
                "mirrorlist": "",
                "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n (...)",
                "check_gpg": true,
                "metadata_expire": "",

    Specify only one of the following attributes: metalink, mirrorlist, or baseurl. The remaining fields are optional.

  3. Save the file using a name corresponding to your RHEL version, for example:


    Alternatively, you can copy the file for your distribution from /usr/share/osbuild-composer/ and modify its content.

  4. Copy the repository file to the directory you created.

    $  cp /usr/share/osbuild-composer/repositories/rhel-version.json /etc/osbuild-composer/repositories/

    Replace rhel-version.json with your RHEL version, for example: rhel-85.json

  5. Using the editor of your choice, edit the baseurl paths in the rhel-85.json file. For example:

    $  vi etc/osbuild-composer/repositories/rhel-85.json

As a result, the repository points to the correct URLs which are copied from the /etc/yum.repos.d/redhat.repo file.

6.3. Overriding a system repository with support for subscriptions

osbuild-composer service can use system subscriptions that are defined in the /etc/yum.repos.d/redhat.repo file. To use a system subscription in osbuild-composer, you need to define a repository override which has:

  • The same baseurl as the repository defined in /etc/yum.repos.d/redhat.repo.
  • The value of ”rhsm”: true defined in the JSON object.



  1. Get the baseurl from the /etc/yum.repos.d/redhat.repo file:

    name = AppStream mirror example
    baseurl =
    enabled = 1
    gpgcheck = 0
    sslverify = 1
    sslcacert = /etc/pki/ca1/ca.crt
    sslclientkey = /etc/pki/ca1/client.key
    sslclientcert = /etc/pki/ca1/client.crt
    metadata_expire = 86400
    enabled_metadata = 0
  2. Configure the repository override to use the same baseurl and set rhsm to true:

        "x86_64": [
                "name": "AppStream mirror example",
                "baseurl": "",
                "gpgkey": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n (...)",
                "check_gpg": true,
                “rhsm": true

osbuild-composer does not automatically use repositories defined in /etc/yum.repos.d/. You need to manually specify them either as a system repository override or as an additional source using composer-cli. System repository overrides are usually used for “BaseOS” and “AppStream” repositories, whereas composer-cli sources are used for all the other repositories.