Virtual Repositories

To simplify access to different repositories, Artifactory allows you to define a virtual repository. A virtual repository is a collection of local, remote, and other virtual repositories with the same package type accessed through a single logical URL.

A virtual repository hides the access details of the underlying repositories, letting users work with a single, well-known URL. The underlying participating repositories and their access rules may be changed without requiring any client-side changes.

📘

Generic Virtual Repositories

By their nature, Virtual Repositories whose package type has been specified as Generic can aggregate repositories of any type. However, generic virtual repositories do not maintain any metadata.

Configure a Virtual Repository

The procedure for configuring a virtual repository includes tabs for mandatory basic settings and a tab for advanced settings.

To configure a virtual repository:

1. In the Administration module, select Repositories.

2. Click Create a Repository and select Virtual from the list.

   

3. In the Select Package Type window, click the icon for the desired package type.

📘

Note

Once you select the package type, it cannot be changed.

The Basic tab for virtual repositories is displayed.

4. In the Basic tab, enter the basic settings for the virtual repository. For details, see Basic Settings for Virtual Repositories and Select Repositories to Include in a Virtual Repository.
5. Optional: In the Advanced tab, enter the advanced settings for the virtual repository.
6. When you have finished configuring the repository, click Create Virtual Repository.

Configure a Virtual Repository using the API

Use the Create Repository REST API to create a virtual repository. For more information, see Create Repository API and Repository Configuration JSON.

Basic Settings for Virtual Repositories

The following basic settings are common for all package types.

❗️

Important

For information about specific settings for particular package types, see Additional Virtual Repository Settings for Specific Package Types.

Using Include and Exclude Patterns

The ability to define an Include Pattern and an Exclude Pattern for virtual repositories (especially when nesting is used) provides a powerful tool you can use to manage artifact requests in your organization.

For example, your organization may have its own artifacts which are hosted both internally in a local repository and also in a remote repository. For optimal performance, you would want these artifacts to be accessed from the local repository rather than from the remote one. To enforce this policy, you can define a virtual repository called "remote-repos" which includes the full set of remote repositories accessed by your organization, and then specify an Excludes Pattern with your organization's groupID. In this way, any attempt to access your internal artifact from a remote repository would be rejected.

Consider another example in which you wish to define a virtual repository for your developers, however, you wish to keep certain artifacts hidden from them. This could be achieved by defining an Excludes Pattern based on groupId, source, or version.

Select Repositories to Include in a Virtual Repository

When creating a virtual repository, you must select the local and remote repositories that will be included. The process is identical for all package types, except for P2 repositories.

To select repositories to include in a virtual repository:

1. In the Administration module, select Repositories.

2. Click Create a Repository and select Virtual from the list.

3. In the Select Package Type window, click the icon for the desired package type. The Basic tab for virtual repositories is displayed.

4. Select the Available Repositories you want to include in the new virtual repository and move them to the Selected Repositories list.

   

   The Selected Repositories section displays the effective list of actual repositories included in this virtual repository. If any of the available repositories you have selected are themselves virtual repositories, then the Selected Repositories section will display the local and remote repositories included within them. The Selected Repositories list is automatically updated if any of the nested virtual repositories change.

✅

Tip

This list can be re-ordered by dragging and dropping within the Selected Repositories list. This is important as it sets the resolution order.

The search/resolution order when requesting artifacts from a virtual repository is always:

1. Local repositories
2. Remote repository caches
3. Remote repositories themselves

The order within these categories is controlled by the order in which they are presented in the Selected Repositories list.

When fulfilling a request for the latest version of an artifact from a virtual repository, Artifactory will search all the included repositories to ensure it retrieves the latest version. This means that Artifactory will still search the remote repository even if it finds a version of the artifact in a local or cache repository, to be certain of returning the most current one. If the remote repository is found to have the latest version, Artifactory will download it and update the remote repository cache.

Virtual Repositories and Projects

Like other resources, a virtual repository can be assigned to a specific project and optionally shared with additional projects. If there are selected local and remote repositories that are not assigned to, or shared with, the same project as the virtual repository, the following message appears in the UI:

Click View to see a list of conflicting repositories. Click the export icon to export the list to a CSV file.

Administrators should be aware of possible repository conflicts to avoid a situation where a user with access to the virtual repository cannot access an aggregated repository because they do not have access to that repository's project.

Nesting

Nesting is a unique feature in Artifactory and facilitates more flexibility in using virtual repositories.

📘

Note

Be careful not to create an "infinite loop" of nested repositories. Artifactory analyzes the internal composition of virtual repositories and will issue a warning if the virtual repository cannot be resolved due to invalid nesting.

Virtual Resolution Order

When an artifact is requested from a virtual repository, the order in which repositories are searched or resolved is local repositories first, then remote repository caches, and finally remote repositories themselves.

Within each of these, the order by which repositories are queried is determined by the order in which they are listed in the configuration, as described in General Resolution Order.

For a virtual repository, you can see the effective search and resolution order in the Included Repositories list view in the Basic settings tab. This is particularly helpful when nesting virtual repositories. For more details, see Configure a Virtual Repository.

Additional Virtual Repository Settings for Specific Package Types

Virtual repositories may have additional settings depending on the package type, as described in the following topics:

• Additional Settings for Alpine Virtual Repositories
• Additional Settings for Bower Virtual Repositories
• Additional Settings for Chef Virtual Repositories
• Additional Settings for Conan Virtual Repositories
• Additional Settings for Conda Virtual Repositories
• Additional Settings for CRAN Virtual Repositories
• Additional Settings for Debian Virtual Repositories
• Additional Settings for Docker Virtual Repositories
• Additional Settings for Go Virtual Repositories
• Additional Settings for Maven/Gradle/Ivy/SBT Virtual Repositories
• Additional Settings for npm Virtual Repositories
• Additional Settings for NuGet Virtual Repositories
• Additional Settings for OCI Virtual Repositories
• Additional Settings for P2 Virtual Repositories

Additional Settings for Alpine Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Alpine repositories.

Additional Settings for Bower Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Bower repositories.

Additional Settings for Chef Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Chef repositories.

Additional Settings for Conan Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Conan repositories.

Additional Settings for Conda Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Conda repositories.

Additional Settings for CRAN Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring CRAN repositories.

Additional Settings for Debian Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Debian repositories.

Additional Settings for Docker Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Docker repositories.

Additional Advanced Settings

Additional Settings for Go Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring Go repositories.

Additional Settings for Maven/Gradle/Ivy/sbt Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, there are specific settings for the following package types;

• Maven
• Gradle
• Ivy
• sbt

Additional Settings for npm Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring npm repositories.

Basic Settings

Advanced Settings

Additional Settings for NuGet Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring NuGet repositories.

Additional Settings for OCI Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring OCI repositories.

Additional Settings for P2 Virtual Repositories

In addition to the basic settings that are common for all virtual repositories, the following settings are available when configuring P2 repositories.