Setting up Repositories

The repository selection is a crucial part of an appliance. KIWI NG allows the end user to customize the selection of repositories and packages via the repository element.

Adding repositories

KIWI NG installs packages into an appliance from the repositories defined in the image description. This means that at least one repository must be defined. Otherwise, KIWI NG cannot fetch any packages.

A repository is added to the description via the repository element which is a child of the top-level image element:

<image schemaversion="8.0" name="{exc_image_base_name}">
    <!-- snip -->
    <repository type="rpm-md" alias="kiwi" priority="1">
        <source path="obs://Virtualization:Appliances:Builder/openSUSE_Leap_15.5"/>
    <repository type="rpm-md" alias="OS" imageinclude="true">
        <source path="{exc_repo}"/>

The above example specifies two repositories:

  1. The repository belonging to the KIWI NG project: obs://Virtualization:Appliances:Builder/openSUSE_Leap_15.5 at the Open Build Service (OBS).

  2. The RPM repository belonging to the OS project: {exc_repo}, at the Open Build Service (OBS). The translated http URL is also included in the final appliance.

The repository element accepts one source child element that contains the URL of the repository in an correct format along with the following optional attributes:

  • imageinclude: Specifies whether the repository should be added to the resulting image. Default is false.

  • imageonly: A repository with imageonly="true" is not available during image build, but is present in the resulting appliance. Default is false.

  • priority: An integer value for all packages in this repository. If the same package is available in more than one repository, then the one with the highest priority is used.

  • alias: Name to use for the repository. It appears as the repository’s name in the image visible via zypper repos or dnf repolist. If alias` is not specified, KIWI NG generates an alias name using hex representation from uuid4.

  • repository_gpgcheck: Specifies whether the repository is configured to perform repository signature validation. If not set, the package manager’s default is used.

  • package_gpgcheck: Boolean value that specifies whether each package’s GPG signature is verified. If omitted, the package manager’s default is used.

  • components: Distribution components used for deb repositories. Default is main.

  • distribution: Distribution name information, used for deb repositories.

  • profiles: List of profiles to which this repository applies.

  • customize: Script to run custom modifications to the repo file or files. Repo files allow for several customization options, but not all of them are supported to be set by kiwi through the current repository schema. As the used options do not follow any standard, and they are not compatible between package managers and distributions, the only way to handle this is through a script hook which is invoked with the repo file as parameter for each file created by KIWI NG.

    An example for a script call to add the module_hotfixes option for a dnf compatible repository configuration could look as follows:

    echo 'module_hotfixes = 1' >> ${repo_file}


    If the script is provided as a relative path, it is expected to be found in the image description directory:

Supported repository paths

The actual location of a repository is specified in the source child element of repository via its only attribute path. KIWI NG supports the following paths types:

  • http://URL or https://URL or ftp://URL: a URL to the repository available via HTTP(s) or FTP.

  • obs://$PROJECT/$REPOSITORY: checks whether the repository $REPOSITORY of the project $PROJECT available on the Open Build Service (OBS). By default, KIWI NG looks for projects on, but this can be overridden using the runtime configuration file (see The Runtime Configuration File). Note that it is not possible to add repositories using the obs:// path from different OBS instances (use direct URLs to the .repo file instead in this case).

  • obsrepositories:/: special path only available for builds using the Open Build Service. The repositories configured for the OBS project where the KIWI NG image resides are made available inside the appliance. This allows you to configure the repositories of your image from OBS itself, without modifying the image description.

  • dir:///path/to/directory or file:///path/to/file: an absolute path to a local directory or file available on the host building the appliance.

  • iso:///path/to/image.iso: the specified ISO image is mounted during the build of the KIWI NG image and a repository is created, pointing to the mounted ISO.