[[repository_types]]
== Repository types

[[sec:flat_dir_resolver]]
=== Flat directory repository

Some projects might prefer to store dependencies on a shared drive or as part of the project source code instead of a binary repository product. If you want to use a (flat) filesystem directory as a repository, simply type:

++++
<sample id="flatDirMulti" dir="userguide/artifacts/defineRepository" title="Flat repository resolver">
    <sourcefile file="build.gradle" snippet="flat-dir-multi"/>
</sample>
++++

This adds repositories which look into one or more directories for finding dependencies. Note that this type of repository does not support any meta-data formats like Ivy XML or Maven POM files. Instead, Gradle will dynamically generate a module descriptor (without any dependency information) based on the presence of artifacts. However, as Gradle prefers to use modules whose descriptor has been created from real meta-data rather than being generated, flat directory repositories cannot be used to override artifacts with real meta-data from other repositories. For example, if Gradle finds only `jmxri-1.2.1.jar` in a flat directory repository, but `jmxri-1.2.1.pom` in another repository that supports meta-data, it will use the second repository to provide the module.

For the use case of overriding remote artifacts with local ones consider using an Ivy or Maven repository instead whose URL points to a local directory. If you only work with flat directory repositories you don't need to set all attributes of a dependency. Please see <<sec:optional_attributes>> for more information.

[[sub:maven_central]]
=== Maven Central repository

Maven Central is a popular repository hosting open source libraries for consumption by Java projects.

To declare the link:https://repo.maven.apache.org/maven2/[central Maven repository] for your build add this to your script:

++++
<sample id="mavenCentral" dir="userguide/artifacts/defineRepository" title="Adding central Maven repository">
    <sourcefile file="build.gradle" snippet="maven-central"/>
</sample>
++++

[[sub:maven_jcenter]]
=== JCenter Maven repository

http://bintray.com[Bintray]'s JCenter is an up-to-date collection of all popular Maven OSS artifacts, including artifacts published directly to Bintray.

To declare the link:https://jcenter.bintray.com[JCenter Maven repository] add this to your build script:

++++
<sample id="mavenJcenter" dir="userguide/artifacts/defineRepository" title="Adding Bintray's JCenter Maven repository">
    <sourcefile file="build.gradle" snippet="maven-jcenter"/>
</sample>
++++

[[sub:maven_google]]
=== Google Maven repository

The Google repository hosts Android-specific artifacts including the Android SDK. For usage examples please see the link:https://developer.android.com/studio/build/dependencies.html#google-maven[relevant documentation].

To declare the link:https://dl.google.com/dl/android/maven2/[Google Maven repository] add this to your build script:

++++
<sample id="mavenGoogleRepo" dir="userguide/artifacts/defineRepository" title="Adding Google Maven repository">
    <sourcefile file="build.gradle" snippet="maven-google"/>
</sample>
++++

[[sub:maven_local]]
=== Local Maven repository

Gradle can consume dependencies available in the link:https://maven.apache.org/guides/introduction/introduction-to-repositories.html[local Maven repository]. Declaring this repository is beneficial for teams that publish to the local Maven repository with one project and consume the artifacts by Gradle in another project.

[NOTE]
====
Gradle stores resolved dependencies in <<sec:dependency_cache,its own cache>>. A build does not need to declare the local Maven repository even if you resolve dependencies from a Maven-based, remote repository.
====

To declare the local Maven cache as a repository add this to your build script:

++++
<sample id="mavenLocalRepo" dir="userguide/artifacts/defineRepository" title="Adding the local Maven cache as a repository">
    <sourcefile file="build.gradle" snippet="maven-local"/>
</sample>
++++

Gradle uses the same logic as Maven to identify the location of your local Maven cache. If a local repository location is defined in a `settings.xml`, this location will be used. The `settings.xml` in `__USER_HOME__/.m2` takes precedence over the `settings.xml` in `__M2_HOME__/conf`. If no `settings.xml` is available, Gradle uses the default location `__USER_HOME__/.m2/repository`.

[[sub:maven_repo]]
=== Custom Maven repositories

Many organizations host dependencies in an in-house Maven repository only accessible within the company's network. Gradle can declare Maven repositories by URL.

For adding a custom Maven repository you can do:

++++
<sample id="mavenLikeRepo" dir="userguide/artifacts/defineRepository" title="Adding custom Maven repository">
    <sourcefile file="build.gradle" snippet="maven-like-repo"/>
</sample>
++++

Sometimes a repository will have the POMs published to one location, and the JARs and other artifacts published at another location. To define such a repository, you can do:

++++
<sample id="mavenLikeRepoWithJarRepo" dir="userguide/artifacts/defineRepository" title="Adding additional Maven repositories for JAR files">
    <sourcefile file="build.gradle" snippet="maven-like-repo-with-jar-repo"/>
</sample>
++++

Gradle will look at the first URL for the POM and the JAR. If the JAR can't be found there, the artifact URLs are used to look for JARs.


[[sec:accessing_password_protected_maven_repositories]]
==== Accessing password-protected Maven repositories

You can specify credentials for Maven repositories secured by basic authentication.

++++
<sample id="mavenPasswordProtectedRepo" dir="userguide/artifacts/defineRepository" title="Accessing password-protected Maven repository">
    <sourcefile file="build.gradle" snippet="authenticated-maven-repo"/>
</sample>
++++

[[sec:ivy_repositories]]
=== Custom Ivy repositories

Organizations might decide to host dependencies in an in-house Ivy repository. Gradle can declare Ivy repositories by URL.

[[sec:defining_an_ivy_repository_with_a_standard_layout]]
==== Defining an Ivy repository with a standard layout

To declare an Ivy repository using the standard layout no additional customization is needed. You just declare the URL.

++++
<sample id="ivyRepository" dir="userguide/artifacts/defineRepository" title="Ivy repository">
    <sourcefile file="build.gradle" snippet="ivy-repo"/>
</sample>
++++


[[sec:defining_a_named_layout_for_an_ivy_repository]]
==== Defining a named layout for an Ivy repository

You can specify that your repository conforms to the Ivy or Maven default layout by using a named layout.

++++
<sample id="ivyRepository" dir="userguide/artifacts/defineRepository" title="Ivy repository with named layout">
    <sourcefile file="build.gradle" snippet="ivy-repo-with-maven-layout"/>
</sample>
++++

Valid named layout values are `'gradle'` (the default), `'maven'`, `'ivy'` and `'pattern'`. See api:org.gradle.api.artifacts.repositories.IvyArtifactRepository#layout(java.lang.String,groovy.lang.Closure)[] in the API documentation for details of these named layouts.

[[sec:defining_custom_pattern_layout_for_an_ivy_repository]]
==== Defining custom pattern layout for an Ivy repository

To define an Ivy repository with a non-standard layout, you can define a `'pattern'` layout for the repository:

++++
<sample id="ivyRepository" dir="userguide/artifacts/defineRepository" title="Ivy repository with pattern layout">
    <sourcefile file="build.gradle" snippet="ivy-repo-with-pattern-layout"/>
</sample>
++++

To define an Ivy repository which fetches Ivy files and artifacts from different locations, you can define separate patterns to use to locate the Ivy files and artifacts:

Each `artifact` or `ivy` specified for a repository adds an _additional_ pattern to use. The patterns are used in the order that they are defined.

++++
<sample id="ivyRepository" dir="userguide/artifacts/defineRepository" title="Ivy repository with multiple custom patterns">
    <sourcefile file="build.gradle" snippet="ivy-repo-with-custom-pattern"/>
</sample>
++++

Optionally, a repository with pattern layout can have its `'organisation'` part laid out in Maven style, with forward slashes replacing dots as separators. For example, the organisation `my.company` would then be represented as `my/company`.

++++
<sample id="ivyRepository" dir="userguide/artifacts/defineRepository" title="Ivy repository with Maven compatible layout">
    <sourcefile file="build.gradle" snippet="ivy-repo-with-m2compatible-layout"/>
</sample>
++++


[[sec:accessing_password_protected_ivy_repositories]]
==== Accessing password-protected Ivy repositories

You can specify credentials for Ivy repositories secured by basic authentication.

++++
<sample id="ivyRepository" dir="userguide/artifacts/defineRepository" title="Ivy repository with authentication">
    <sourcefile file="build.gradle" snippet="authenticated-ivy-repo"/>
</sample>
++++

[[sub:supported_transport_protocols]]
=== Supported repository transport protocols

Maven and Ivy repositories support the use of various transport protocols. At the moment the following protocols are supported:

.Repository transport protocols
[cols="a,a", options="header"]
|===
| Type
| Credential types

| `file`
| none

| `http`
| username/password

| `https`
| username/password

| `sftp`
| username/password

| `s3`
| access key/secret key/session token or Environment variables

| `gcs`
| https://developers.google.com/identity/protocols/application-default-credentials[default application credentials] sourced from well known files, Environment variables etc.
|===

[NOTE]
====
Username and password should never be checked in plain text into version control as part of your build file. You can store the credentials in a local `gradle.properties` file and use one of the open source Gradle plugins for encrypting and consuming credentials e.g. the link:https://plugins.gradle.org/plugin/nu.studer.credentials[credentials plugin].
====

The transport protocol is part of the URL definition for a repository. The following build script demonstrates how to create a HTTP-based Maven and Ivy repository:

++++
<sample id="mavenIvyRepositoriesNoAuth" dir="userguide/artifacts/defineRepository" title="Declaring a Maven and Ivy repository">
    <sourcefile file="build.gradle" snippet="maven-ivy-repository-no-auth"/>
</sample>
++++

The following example shows how to declare SFTP repositories:

++++
<sample id="mavenIvyRepositoriesAuth" dir="userguide/artifacts/defineRepository" title="Using the SFTP protocol for a repository">
    <sourcefile file="build.gradle" snippet="maven-ivy-repository-auth"/>
</sample>
++++

When using an AWS S3 backed repository you need to authenticate using api:org.gradle.api.credentials.AwsCredentials[], providing access-key and a private-key. The following example shows how to declare a S3 backed repository and providing AWS credentials:

++++
<sample id="mavenIvyS3RepositoriesAuth" dir="userguide/artifacts/defineRepository" title="Declaring a S3 backed Maven and Ivy repository">
    <sourcefile file="build.gradle" snippet="maven-ivy-s3-repository"/>
</sample>
++++

You can also delegate all credentials to the AWS sdk by using the AwsImAuthentication. The following example shows how:

++++
<sample id="mavenIvyS3RepositoriesAuthWithIam" dir="userguide/artifacts/defineRepository" title="Declaring a S3 backed Maven and Ivy repository using IAM">
    <sourcefile file="build.gradle" snippet="maven-ivy-s3-repository-with-iam"/>
</sample>
++++

When using a Google Cloud Storage backed repository default application credentials will be used with no further configuration required:

++++
<sample id="mavenIvyGCSRepositoriesAuthDefault" dir="userguide/artifacts/defineRepository" title="Declaring a Google Cloud Storage backed Maven and Ivy repository using default application credentials">
    <sourcefile file="build.gradle" snippet="maven-ivy-gcs-repository"/>
</sample>
++++

[[sub:s3_configuration_properties]]
==== S3 configuration properties

The following system properties can be used to configure the interactions with s3 repositories:

.S3 configuration properties
[cols="a,a", options="header"]
|===
| Property
| Description

| org.gradle.s3.endpoint
| Used to override the AWS S3 endpoint when using a non AWS, S3 API compatible, storage service.

| org.gradle.s3.maxErrorRetry
| Specifies the maximum number of times to retry a request in the event that the S3 server responds with a HTTP 5xx status code. When not specified a default value of 3 is used.
|===

[[sub:s3_url_formats]]
==== S3 URL formats

S3 URL's are 'virtual-hosted-style' and must be in the following format `s3://&lt;bucketName&gt;[.&lt;regionSpecificEndpoint&gt;]/&lt;s3Key&gt;`

e.g. `s3://myBucket.s3.eu-central-1.amazonaws.com/maven/release`

* `myBucket` is the AWS S3 bucket name.
* `s3.eu-central-1.amazonaws.com` is the _optional_ http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region[region specific endpoint].
* `/maven/release` is the AWS S3 key (unique identifier for an object within a bucket)


[[sub:s3_proxy_settings]]
==== S3 proxy settings

A proxy for S3 can be configured using the following system properties:

* `https.proxyHost`
* `https.proxyPort`
* `https.proxyUser`
* `https.proxyPassword`
* `http.nonProxyHosts`

If the 'org.gradle.s3.endpoint' property has been specified with a http (not https) URI the following system proxy settings can be used:

* `http.proxyHost`
* `http.proxyPort`
* `http.proxyUser`
* `http.proxyPassword`
* `http.nonProxyHosts`

[[s3_v4_signatures]]
==== AWS S3 V4 Signatures (AWS4-HMAC-SHA256)

Some of the AWS S3 regions (eu-central-1 - Frankfurt) require that all HTTP requests are signed in accordance with AWS's http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html[signature version 4]. It is recommended to specify S3 URL's containing the region specific endpoint when using buckets that require V4 signatures. e.g. `s3://somebucket.s3.eu-central-1.amazonaws.com/maven/release`

[NOTE]
====
When a region-specific endpoint is not specified for buckets requiring V4 Signatures, Gradle will use the default AWS region (us-east-1) and the
following warning will appear on the console:

Attempting to re-send the request to .... with AWS V4 authentication. To avoid this warning in the future, please use region-specific endpoint to access buckets located in regions that require V4 signing.

Failing to specify the region-specific endpoint for buckets requiring V4 signatures means:

* `3 round-trips to AWS, as opposed to one, for every file upload and download.`
* `Depending on location - increased network latencies and slower builds.`
* `Increased likelihood of transmission failures.`
====

[[sub:gcs_configuration_properties]]
==== Google Cloud Storage configuration properties

The following system properties can be used to configure the interactions with link:https://cloud.google.com/storage/[Google Cloud Storage] repositories:

.Google Cloud Storage configuration properties
[cols="a,a", options="header"]
|===
| Property
| Description

| org.gradle.gcs.endpoint
| Used to override the Google Cloud Storage endpoint when using a non-Google Cloud Platform, Google Cloud Storage API compatible, storage service.

| org.gradle.gcs.servicePath
| Used to override the Google Cloud Storage root service path which the Google Cloud Storage client builds requests from, defaults to `/`.
|===

[[sub:gcs_url_formats]]
==== Google Cloud Storage URL formats

Google Cloud Storage URL's are 'virtual-hosted-style' and must be in the following format `gcs://&lt;bucketName&gt;/&lt;objectKey&gt;`

e.g. `gcs://myBucket/maven/release`

* `myBucket` is the Google Cloud Storage bucket name.
* `/maven/release` is the Google Cloud Storage key (unique identifier for an object within a bucket)

[[sub:authentication_schemes]]
==== Configuring HTTP authentication schemes

When configuring a repository using HTTP or HTTPS transport protocols, multiple authentication schemes are available. By default, Gradle will attempt to use all schemes that are supported by the Apache HttpClient library, http://hc.apache.org/httpcomponents-client-ga/tutorial/html/authentication.html#d5e625[documented here]. In some cases, it may be preferable to explicitly specify which authentication schemes should be used when exchanging credentials with a remote server. When explicitly declared, only those schemes are used when authenticating to a remote repository. The following example show how to configure a repository to use only digest authentication:

++++
<sample id="digestAuthentication" dir="userguide/artifacts/defineRepository" title="Configure repository to use only digest authentication">
    <sourcefile file="build.gradle" snippet="digest-authentication"/>
</sample>
++++

Currently supported authentication schemes are:

.Authentication schemes
[cols="a,a", options="header"]
|===
| Type
| Description

| api:org.gradle.authentication.http.BasicAuthentication[]
| Basic access authentication over HTTP. When using this scheme, credentials are sent preemptively.

| api:org.gradle.authentication.http.DigestAuthentication[]
| Digest access authentication over HTTP.
|===

[[sub:preemptive_authentication]]
==== Using preemptive authentication

Gradle's default behavior is to only submit credentials when a server responds with an authentication challenge in the form of a HTTP 401 response. In some cases, the server will respond with a different code (ex. for repositories hosted on GitHub a 404 is returned) causing dependency resolution to fail. To get around this behavior, credentials may be sent to the server preemptively. To enable preemptive authentication simply configure your repository to explicitly use the api:org.gradle.authentication.http.BasicAuthentication[] scheme:

++++
<sample id="preemptiveAuthentication" dir="userguide/artifacts/defineRepository" title="Configure repository to use preemptive authentication">
    <sourcefile file="build.gradle" snippet="preemptive-authentication"/>
</sample>
++++