Basic Settings for Virtual Repositories

JFrog Artifactory Documentation

JFrog Artifactory
Content Type
User Guide

The following basic settings are common for all package types.




Package Type

The package type must be specified when the repository is created, and once set, cannot be changed.

Repository Key

The repository key is a mandatory, unique identifier for the repository. It cannot begin with a number or contain spaces or special characters.


Defines the environment in which this repository will reside. Environments aggregate project resources (repositories, Pipeline sources, etc.) to simplify their management. For more information, see Environments.Environments

Repository Layout

Sets the layout that the repository should use for storing and identifying modules. A recommended layout that corresponds to the package type defined is suggested.

Public Description

A free text field that describes the content and purpose of the repository. This description can be viewed by all users with access to the repository.

Internal Description

A free text field to add additional notes about the repository. These notes are visible only to the administrator.

Include and Exclude Patterns

The Include Patterns and Exclude Patterns fields provide a way to filter out specific repositories when resolving the location of different artifacts.

In each field, you can specify a list of Ant-like patterns to filter in and filter out artifact queries. Filtering works by subtracting the excluded patterns (default is none) from the included patterns (default is all).


Consider that the Include Patterns and Exclude Patterns for a repository are as follows:

Include Patterns: org/apache/**,com/acme/**

Exclude Patterns:


In this example, the repository is searched for org/apache/maven/parent/1/1.pom and com/acme/project-x/core/1.0/nit-1.0.jar but not for com/acme/exp-project/core/1.1/san-1.1.jar because com/acme/exp-project/** is specified as an Exclude pattern.

In addition, in the Repositories section of the Basic settings screen you select the Available Repositories you want to include in the new virtual repository and move them to the Selected Repositories list.

This list can be re-ordered by dragging and dropping within the Selected Repositories list.


The Included 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 Included Repositories section will display the local and remote repositories included within them. The Included Repository list is automatically updated in case any of the nested virtual repositories change.


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 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.


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


You should take care 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.

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. To learn more, see this Knowledge Base article.

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.