# Declaring Repositories

version 5.4.1

Gradle can resolve dependencies from one or many repositories based on Maven, Ivy or flat directory formats. Check out the full reference on all types of repositories for more information.

## Declaring a publicly-available repository

Organizations building software may want to leverage public binary repositories to download and consume open source dependencies. Popular public repositories include Maven Central, Bintray JCenter and the Google Android repository. Gradle provides built-in shortcut methods for the most widely-used repositories.

Figure 1. Declaring a repository with the help of shortcut methods

To declare JCenter as repository, add this code to your build script:

Example 1. Declaring JCenter repository as source for resolving dependencies
build.gradle

    repositories {
        jcenter()
    }

build.gradle.kts

    repositories {
        jcenter()
    }

Under the covers Gradle resolves dependencies from the respective URL of the public repository defined by the shortcut method. All shortcut methods are available via the RepositoryHandler API. Alternatively, you can spell out the URL of the repository for more fine-grained control.

## Declaring a custom repository by URL

Most enterprise projects set up a binary repository available only within an intranet. In-house repositories enable teams to publish internal binaries, setup user management and security measure and ensure uptime and availability. Specifying a custom URL is also helpful if you want to declare a less popular, but publicly-available repository.

Add the following code to declare an in-house repository for your build reachable through a custom URL.

Example 2. Declaring a custom repository by URL
build.gradle

    repositories {
        maven {
          url 'http://repo.mycompany.com/maven2'
        }
    }

build.gradle.kts

    repositories {
        maven {
          url = uri("http://repo.mycompany.com/maven2")
        }
    }

Repositories with custom URLs can be specified as Maven or Ivy repositories by calling the corresponding methods available on the RepositoryHandler API. Gradle supports other protocols than `http` or `https` as part of the custom URL e.g. `file`, `sftp` or `s3`. For a full coverage see the reference manual on supported transport protocols.

You can also define your own repository layout by using `ivy { }` repositories as they are very flexible in terms of how modules are organised in a repository.

## Declaring multiple repositories

You can define more than one repository for resolving dependencies. Declaring multiple repositories is helpful if some dependencies are only available in one repository but not the other. You can mix any type of repository described in the reference section.

This example demonstrates how to declare various shortcut and custom URL repositories for a project:

Example 3. Declaring multiple repositories
build.gradle

    repositories {
        jcenter()
        maven {
            url "https://maven.springframework.org/release"
        }
        maven {
            url "https://maven.restlet.com"
        }
    }

build.gradle.kts

    repositories {
        jcenter()
        maven {
            url = uri("https://maven.springframework.org/release")
        }
        maven {
            url = uri("https://maven.restlet.com")
        }
    }

✨ | The order of declaration determines how Gradle will check for dependencies at runtime. If Gradle finds a module descriptor in a particular repository, it will attempt to download all of the artifacts for that module from the same repository. You can learn more about the inner workings of Gradle’s resolution mechanism.

## Matching repositories to dependencies

✨ | Matching repositories to dependencies is an incubating feature.

Gradle exposes an API to declare what a repository may or may not contain. There are different use cases for it:

- performance, when you know a dependency will never be found in a specific repository

- security, by avoiding leaking what dependencies are used in a private project

- reliability, when some repositories contain corrupted metadata or artifacts

It’s even more important when considering that order of repositories matter.

### Declaring a repository filter

Example 4. Declaring repository contents
build.gradle

    repositories {
        maven {
            url "http://repo.mycompany.com/maven2"
            content {
                // this repository *only* contains artifacts with group "my.company"
                includeGroup "my.company"
            }
        }
        jcenter {
            content {
                // this repository contains everything BUT artifacts with group starting with "my.company"
                excludeGroupByRegex "my\\.company.*"
            }
        }
    }

build.gradle.kts

    repositories {
        maven {
            url = uri("http://repo.mycompany.com/maven2")
            content {
                // this repository *only* contains artifacts with group "my.company"
                includeGroup("my.company")
            }
        }
        jcenter {
            content {
                // this repository contains everything BUT artifacts with group starting with "my.company"
                excludeGroupByRegex("my\\.company.*")
            }
        }
    }

By default, repositories include everything and exclude nothing:

- If you declare an include, then it excludes everything but what is included.

- If you declare an exclude, then it includes everything but what is excluded.

- If you declare both includes and excludes, then it includes only what is explicitly included and not excluded.

It is possible to filter either by explicit group, module or version, either strictly or using regular expressions. See RepositoryContentDescriptor for details.

### Maven repository filtering

For Maven repositories, it’s often the case that a repository would either contain releases or snapshots. Gradle lets you declare what kind of artifacts are found in a repository using this DSL:

Example 5. Splitting snapshots and releases
build.gradle

    repositories {
        maven {
            url "http://repo.mycompany.com/releases"
            mavenContent {
                releasesOnly()
            }
        }
        maven {
            url "http://repo.mycompany.com/snapshots"
            mavenContent {
                snapshotsOnly()
            }
        }
    }

build.gradle.kts

    repositories {
        maven {
            url = uri("http://repo.mycompany.com/releases")
            mavenContent {
                releasesOnly()
            }
        }
        maven {
            url = uri("http://repo.mycompany.com/snapshots")
            mavenContent {
                snapshotsOnly()
            }
        }
    }