Chapter 3. Managing image builder repositories

3.1. Image builder default system repositories

The osbuild-composer back end 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. This includes the Red Hat official repository, which contains the base system RPMs to install additional software or update already installed programs to newer versions. If you want 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 there 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.

3.2. Overriding a system repository

You can configure a repository override for image builder in the /etc/osbuild-composer/repositories directory with the following steps.


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.


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


  1. Create a directory where you want to store your repository overrides:

    $ sudo mkdir -p /etc/osbuild-composer/repositories
  2. You can create your own JSON file structure.
  3. Create a JSON file, using a name corresponding to your RHEL version. Alternatively, you can copy the file for your distribution from /usr/share/osbuild-composer/ and modify its content.

    For RHEL 8, use /etc/osbuild-composer/repositories/rhel-87.json.

  4. Add the following structure to your JSON file, 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 - offers increased availability and error correction on a repository link.
    • mirrorlist - a list of URLs that point to package repositories.
    • baseurl - a link to the repository that contains the packages required for the installation.

      The remaining fields are optional.

      1. Alternatively, you can copy the JSON file for your distribution.

        1. Copy the repository file to the directory you created. In the following command, replace rhel-version.json with your RHEL version, for example: rhel-8.json.

          $  cp /usr/share/osbuild-composer/repositories/rhel-version.json /etc/osbuild-composer/repositories/
  5. Using a text editor, edit the baseurl paths in the rhel-8.json file and save it. For example:

    $ vi /etc/osbuild-composer/repositories/rhel-version.json
  6. Restart the osbuild-composer.service:

    $ sudo systemctl restart osbuild-composer.service


  • Check if the repository points to the correct URLs:

    $ cat /etc/yum.repos.d/redhat.repo

    You can see that the repository points to the correct URLs which are copied from the /etc/yum.repos.d/redhat.repo file.

3.3. Overriding a system repository with support for subscriptions

The 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, define a repository override that 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. Obtain the baseurl from the /etc/yum.repos.d/redhat.repo file:

    # cat /etc/yum.repos.d/redhat.repo
    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.

As a result, image builder reads the /etc/yum.repos.d/redhat.repo file from the host system and uses it as a source of subscriptions.