[[declaring-repositories]]
= Declaring repositories

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

[[sec:declaring_public_repository]]
== 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 <<#sub:maven_central,Maven Central>> and the <<#sub:maven_google,Google Android>> repository.
Gradle provides built-in shorthand notations for these widely-used repositories.

.Declaring a repository with the help of shorthand notations
image::dependency-management-shortcut-repositories.png[]

Under the covers Gradle resolves dependencies from the respective URL of the public repository defined by the shorthand notation.
All shorthand notations are available via the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.RepositoryHandler.html[RepositoryHandler] API.
Alternatively, you can <<#sec:declaring_custom_repository,spell out the URL of the repository>> for more fine-grained control.

[[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/[Maven Central repository] for your build add this to your script:

.Adding central Maven repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-central]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-central]"]
====

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

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

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

.Adding Google Maven repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-google]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-google]"]
====

[[sec:declaring_custom_repository]]
== 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.

Repositories with custom URLs can be specified as Maven or Ivy repositories by calling the corresponding methods available on the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.RepositoryHandler.html[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 <<#sec:repository-types,section on supported repository types>>.

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

[[sec:declaring_multiple_repositories]]
== 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 <<#sec:repository-types,reference section>>.

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

.Declaring multiple repositories
====
include::sample[dir="snippets/dependencyManagement/declaringRepositories-multipleRepositories/groovy",files="build.gradle[tags=multiple-repositories]"]
include::sample[dir="snippets/dependencyManagement/declaringRepositories-multipleRepositories/kotlin",files="build.gradle.kts[tags=multiple-repositories]"]
====

[NOTE]
====
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 <<dependency_resolution.adoc#sec:how-gradle-downloads-deps, dependency downloads>>.
====

=== Strict limitation to declared repositories

Maven POM metadata can reference additional repositories.
These will be _ignored_ by Gradle, which will only use the repositories declared in the build itself.

[NOTE]
====
This is a reproducibility safe-guard but also a security protection.
Without it, an updated version of a dependency could pull artifacts from anywhere into your build.
====

[[sec:repository-types]]
== Supported repository types

Gradle supports a wide range of sources for dependencies, both in terms of format and in terms of connectivity.
You may resolve dependencies from:

* Different formats
** a <<#sec:maven_repo,Maven compatible>> artifact repository (e.g: Maven Central)
** an <<#sec:ivy_repositories,Ivy compatible>> artifact repository (including custom layouts)
** <<#sub:flat_dir_resolver,local (flat) directories>>
* with different connectivity
** <<#sec:authentication_schemes, authenticated repositories>>
** a wide variety of <<#sec:supported_transport_protocols,remote protocols>> such as HTTPS, SFTP, AWS S3 and Google Cloud Storage

[[sub: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:

.Flat repository resolver
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=flat-dir-multi]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=flat-dir-multi]"]
====

This adds repositories which look into one or more directories for finding dependencies.

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.

[NOTE]
====
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 declared in the build.

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.

[[sub:local-repos]]
=== Local repositories

The following sections describe repositories format, Maven or Ivy.
These can be declared as local repositories, using a local filesystem path to access them.

The difference with the flat directory repository is that they do respect a format and contain metadata.

When such a repository is configured, Gradle totally bypasses its <<dependency_resolution.adoc#sec:dependency_cache,dependency cache>> for it as there can be no guarantee that content may not change between executions.
Because of that limitation, they can have a performance impact.

They also make build reproducibility much harder to achieve and their use should be limited to tinkering or prototyping.

[[sec:maven_repo]]
== 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:

.Adding custom Maven repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-like-repo]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-like-repo]"]
====

[[sub:custom-maven-repo]]
=== Setting up composite Maven repositories

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:

.Adding additional Maven repositories for JAR files
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-like-repo-with-jar-repo]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-like-repo-with-jar-repo]"]
====

Gradle will look at the base `url` location for the POM and the JAR.
If the JAR can't be found there, the extra `artifactUrls` are used to look for JARs.

[[sub:accessing_secured_maven_repositories]]
=== Accessing authenticated Maven repositories

You can specify credentials for Maven repositories secured by different type of authentication.

See <<#sec:supported_transport_protocols>> for authentication options.

[[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 <<dependency_resolution.adoc#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.
====

[WARNING]
====
Before adding Maven local as a repository, you should <<#sec:case-for-maven-local, make sure this is really required>>.
====

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

.Adding the local Maven cache as a repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-local]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-local]"]
====

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

[[sec:case-for-maven-local]]
== The case for mavenLocal()

As a general advice, you should avoid adding `mavenLocal()` as a repository.
There are different issues with using `mavenLocal()` that you should be aware of:

* Maven uses it as a cache, not a repository, meaning it can contain partial modules.
** For example, if Maven never downloaded the source or javadoc files for a given module, Gradle will not find them either since it <<dependency_resolution.adoc#sec:how-gradle-downloads-deps,searches for files in a single repository>> once a module has been found.
* As a <<sub:local-repos,local repository>>, Gradle does not trust its content, because:
** Origin of artifacts cannot be tracked, which is a correctness and security problem
** Artifacts can be easily overwritten, which is a security, correctness and reproducibility problem
* To mitigate the fact that metadata and/or artifacts can be changed, Gradle does not perform <<dependency_resolution.adoc#sec:dependency_cache,any caching>> for <<sub:local-repos,local repositories>>
** As a consequence, your builds are slower
** Given that order of repositories is important, adding `mavenLocal()` _first_ means that all your builds are going to be slower

There are a few cases where you might have to use `mavenLocal()`:

* For interoperability with Maven
** For example, project A is built with Maven, project B is built with Gradle, and you need to share the artifacts during development
** It is _always_ preferable to use an internal full featured repository instead
** In case this is not possible, you should limit this to _local builds only_
* For interoperability with Gradle itself
** In a multi-repository world, you want to check that changes to project A work with project B
** It is preferable to use <<composite_builds.adoc#composite_builds, composite builds>> for this use case
** If for some reason neither composite builds nor full featured repository are possible, then `mavenLocal()` is a last resort option

After all these warnings, if you end up using `mavenLocal()`, consider combining it with <<#sec:repository-content-filtering,a repository filter>>.
This will make sure it only provides what is expected and nothing else.

[[sec:ivy_repositories]]
== Ivy repositories

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

[[sub: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.

.Ivy repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=ivy-repo]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=ivy-repo]"]
====

[[sub: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.

.Ivy repository with named layout
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=ivy-repo-with-maven-layout]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=ivy-repo-with-maven-layout]"]
====

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

[[sub: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:

.Ivy repository with pattern layout
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=ivy-repo-with-pattern-layout]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=ivy-repo-with-pattern-layout]"]
====

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.

.Ivy repository with multiple custom patterns
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=ivy-repo-with-custom-pattern]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=ivy-repo-with-custom-pattern]"]
====

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

.Ivy repository with Maven compatible layout
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=ivy-repo-with-m2compatible-layout]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=ivy-repo-with-m2compatible-layout]"]
====

[[sub:accessing_secured_ivy_repositories]]
=== Accessing authenticated Ivy repositories

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

.Ivy repository with authentication
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=authenticated-ivy-repo]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=authenticated-ivy-repo]"]
====

See <<#sec:supported_transport_protocols>> for authentication options.

[[sec:repository-content-filtering]]
== Repository content filtering

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 the declared order of repositories matter.

[[sec:declaring-repository-filter]]
=== Declaring a repository filter

.Declaring repository contents
====
include::sample[dir="snippets/dependencyManagement/declaringRepositories-filtering/groovy",files="build.gradle[tags=repository-filter]"]
include::sample[dir="snippets//dependencyManagement/declaringRepositories-filtering/kotlin",files="build.gradle.kts[tags=repository-filter]"]
====

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.
When using a strict version, it is possible to use a version range, using <<single_versions.adoc#single-version-declarations,the format supported>> by Gradle.
In addition, there are filtering options by resolution context: configuration name or even configuration attributes.
See link:{javadocPath}/org/gradle/api/artifacts/repositories/RepositoryContentDescriptor.html[RepositoryContentDescriptor] for details.

=== Declaring content exclusively found in one repository

Filters declared using the <<#sec:declaring-repository-filter,repository-level content filter>> are not exclusive.
This means that declaring that a repository _includes_ an artifact doesn't mean that the other repositories can't have it either: you must declare what every repository contains in extension.

Alternatively, Gradle provides an API which lets you declare that a repository _exclusively includes_ an artifact.
If you do so:

- an artifact declared in a repository _can't_ be found in any other
- exclusive repository content must be declared in extension (just like for <<#sec:declaring-repository-filter, repository-level content>>)

.Declaring exclusive repository contents
====
include::sample[dir="snippets/dependencyManagement/declaringRepositories-filtering/groovy",files="build.gradle[tags=exclusive-repository-filter]"]
include::sample[dir="snippets/dependencyManagement/declaringRepositories-filtering/kotlin",files="build.gradle.kts[tags=exclusive-repository-filter]"]
====

It is possible to filter either by explicit _group_, _module_ or _version_, either strictly or using regular expressions.
See link:{javadocPath}/org/gradle/api/artifacts/repositories/InclusiveRepositoryContentDescriptor.html[InclusiveRepositoryContentDescriptor] for details.

[NOTE]
====
If you leverage exclusive content filtering in the <<plugins.adoc#sec:custom_plugin_repositories,`pluginManagement` section of the `settings.gradle(.kts)`>>, it becomes illegal to add more repositories through the project `buildscript.repositories`.
In that case, the build configuration will fail.

Your options are either to declare all repositories in settings or to use non-exclusive content filtering.
====

=== Maven repository filtering

For <<sec:maven_repo,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:

.Splitting snapshots and releases
====
include::sample[dir="snippets/dependencyManagement/declaringRepositories-filtering/groovy",files="build.gradle[tags=repository-snapshots]"]
include::sample[dir="snippets/dependencyManagement/declaringRepositories-filtering/kotlin",files="build.gradle.kts[tags=repository-snapshots]"]
====

[[sec:supported_metadata_sources]]
== Supported metadata sources

When searching for a module in a repository, Gradle, by default, checks for <<declaring_dependencies.adoc#sec:supported-metadata-formats,supported metadata file formats>> in that repository.
In a Maven repository, Gradle looks for a `.pom` file, in an ivy repository it looks for an `ivy.xml` file and in a flat directory repository it looks directly for `.jar` files as it does not expect any metadata.
Starting with 5.0, Gradle also looks for `.module` (Gradle module metadata) files.

However, if you define a customized repository you might want to configure this behavior.
For example, you can define a Maven repository without `.pom` files but only jars.
To do so, you can configure _metadata sources_ for any repository.

.Maven repository that supports artifacts without metadata
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-repo-with-metadata-sources]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-repo-with-metadata-sources]"]
====

You can specify multiple sources to tell Gradle to keep looking if a file was not found.
In that case, the order of checking for sources is predefined.

The following metadata sources are supported:

.Supported metadata sources
[%header%autowidth,compact]
|===
| Metadata source | Description | Order | Maven | Ivy / flat dir

| `gradleMetadata()`
| Look for Gradle `.module` files
| 1st
| yes
| yes

| `mavenPom()`
| Look for Maven `.pom` files
| 2nd
| yes
| yes

| `ivyDescriptor()`
| Look for `ivy.xml` files
| 2nd
| no
| yes

| `artifact()`
| Look directly for artifact
| 3rd
| yes
| yes
|===

[NOTE]
====
The defaults for Ivy and Maven repositories change with Gradle 6.0. Before 6.0, `artifact()` was included in the defaults.
Leading to some inefficiency when modules are missing completely.
To restore this behavior, for example, for Maven central you can use `mavenCentral { metadataSources { mavenPom(); artifact() } }`.
In a similar way, you can opt into the new behavior in older Gradle versions using `mavenCentral { metadataSources { mavenPom() } }`
====

Since Gradle 5.3, when parsing a metadata file, be it Ivy or Maven, Gradle will look for a marker indicating that a matching Gradle Module Metadata files exists.
If it is found, it will be used instead of the Ivy or Maven file.

Starting with Gradle 5.6, you can disable this behavior by adding `ignoreGradleMetadataRedirection()` to the metadataSources declaration.

.Maven repository that does not use gradle metadata redirection
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-repo-with-ignore-gradle-metadata-redirection]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-repo-with-ignore-gradle-metadata-redirection]"]
====

[[sec:plugin-vs-build-repos]]
== Plugin repositories vs. build repositories

Gradle will use repositories at two different phases during your build.

The first phase is when <<build_lifecycle.adoc#sec:build_phases,configuring your build>> and loading the plugins it applied.
To do that Gradle will use a special set of repositories.

The second phase is during dependency resolution.
At this point Gradle will use the repositories declared in your project, as shown in the previous sections.

[[sub:plugin-repos]]
=== Plugin repositories

By default Gradle will use the http://plugins.gradle.org[Gradle plugin portal] to look for plugins.

However, for different reasons, there are plugins available in other, public or not, repositories.
When a build requires one of these plugins, additional repositories need to be specified so that Gradle knows where to search.

As the way to declare the repositories and what they are expected to contain depends on the way the plugin is applied, it is best to refer to <<plugins.adoc#sec:custom_plugin_repositories, Custom Plugin Repositories>>.

[[sub:centralized-repository-declaration]]
== Centralizing repositories declaration

Instead of declaring repositories in every subproject of your build or via an `allprojects` block, Gradle offers a way to declare them in a central place for all project.

NOTE: Central declaration of repositories is an incubating feature

Repositories used by convention by every subproject can be declared in the `settings.gradle(.kts)` file:

.Declaring a Maven repository in settings
====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=declare_repositories_settings]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=declare_repositories_settings]"]
====

The `dependencyResolutionManagement` repositories block accepts the same notations as in a project, which includes Maven or Ivy repositories, with or without credentials, etc.

By default, repositories declared by a project will *override* whatever is declared in settings.
You can change this behavior to make sure that you always use the settings repositories:

.Preferring settings repositories
====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=prefer_settings]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=prefer_settings]"]
====

[[sub:fail_build_on_project_repositories]]

If, for some reason, a project or a plugin declares a repository in a project, Gradle would warn you.
You can however make it _fail the build_ if you want to enforce that only settings repositories are used:

.Enforcing settings repositories
====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=enforce_settings]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=enforce_settings]"]
====

Eventually, the default is equivalent to setting `PREFER_PROJECT`:

.Preferring project repositories
====
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/groovy",files="settings.gradle[tags=prefer_projects]"]
include::sample[dir="snippets/artifacts/defineRepositoryInSettings/kotlin",files="settings.gradle.kts[tags=prefer_projects]"]
====

[[sec: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
[%header%autowidth,compact]
|===
| Type | Credential types | Link

| `file`
| none
|

| `http`
| username/password
| <<#sec:authentication_schemes, Documentation>>

| `https`
| username/password
| <<#sec:authentication_schemes, Documentation>>

| `sftp`
| username/password
| <<#sec:authentication_schemes, Documentation>>

| `s3`
| access key/secret key/session token or Environment variables
| <<#sec:s3-repositories,Documentation>>

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

[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 HTTP-based Maven and Ivy repositories:

.Declaring a Maven and Ivy repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-ivy-repository-no-auth]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-ivy-repository-no-auth]"]
====

The following example shows how to declare SFTP repositories:

.Using the SFTP protocol for a repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-ivy-repository-auth]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-ivy-repository-auth]"]
====

For details on HTTP related authentication, see the section <<#sec:authentication_schemes>>.

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

.Declaring an S3 backed Maven and Ivy repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-ivy-s3-repository]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-ivy-s3-repository]"]
====

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

.Declaring an S3 backed Maven and Ivy repository using IAM
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-ivy-s3-repository-with-iam]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-ivy-s3-repository-with-iam]"]
====

For details on AWS S3 related authentication, see the section <<#sec:s3-repositories>>.

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

.Declaring a Google Cloud Storage backed Maven and Ivy repository using default application credentials
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=maven-ivy-gcs-repository]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=maven-ivy-gcs-repository]"]
====

For details on Google GCS related authentication, see the section <<#sec:gcs-repositories>>.

[[sec:authentication_schemes]]
== HTTP(S) authentication schemes configuration

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.

You can specify credentials for Maven repositories secured by basic authentication using link:{javadocPath}/org/gradle/api/credentials/PasswordCredentials.html[PasswordCredentials].

.Accessing password-protected Maven repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=authenticated-maven-repo]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=authenticated-maven-repo]"]
====


The following example show how to configure a repository to use only link:{javadocPath}/org/gradle/authentication/http/DigestAuthentication.html[DigestAuthentication]:

.Configure repository to use only digest authentication
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=digest-authentication]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=digest-authentication]"]
====

Currently supported authentication schemes are:

link:{javadocPath}/org/gradle/authentication/http/BasicAuthentication.html[BasicAuthentication]::
Basic access authentication over HTTP. When using this scheme, credentials are sent preemptively.

link:{javadocPath}/org/gradle/authentication/http/DigestAuthentication.html[DigestAuthentication]::
Digest access authentication over HTTP.

link:{javadocPath}/org/gradle/authentication/http/HttpHeaderAuthentication.html[HttpHeaderAuthentication]::
Authentication based on any custom HTTP header, e.g. private tokens, OAuth tokens, etc.

[[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 an 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 link:{javadocPath}/org/gradle/authentication/http/BasicAuthentication.html[BasicAuthentication] scheme:

.Configure repository to use preemptive authentication
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=preemptive-authentication]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=preemptive-authentication]"]
====

[[sub:http-header-auth]]
=== Using HTTP header authentication

You can specify any HTTP header for secured Maven repositories requiring token, OAuth2 or other HTTP header based authentication using link:{javadocPath}/org/gradle/api/credentials/HttpHeaderCredentials.html[HttpHeaderCredentials] with link:{javadocPath}/org/gradle/authentication/http/HttpHeaderAuthentication.html[HttpHeaderAuthentication].

.Accessing header-protected Maven repository
====
include::sample[dir="snippets/artifacts/defineRepository/groovy",files="build.gradle[tags=header-authenticated-maven-repo]"]
include::sample[dir="snippets/artifacts/defineRepository/kotlin",files="build.gradle.kts[tags=header-authenticated-maven-repo]"]
====


[[sec:s3-repositories]]
== AWS S3 repositories configuration

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

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

`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://<bucketName>[.<regionSpecificEndpoint>]/<s3Key>
----

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` (NOTE: this is not a typo.)

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`

[[sub: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, 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:s3_cross_account]]
==== AWS S3 Cross Account Access

Some organizations may have multiple AWS accounts, e.g. one for each team. The AWS account of the bucket owner is often different from the artifact publisher and consumers. The bucket owner needs to be able to grant the consumers access otherwise the artifacts will only be usable by the publisher's account. This is done by adding the `bucket-owner-full-control` link:https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl[Canned ACL] to the uploaded objects. Gradle will do this in every upload. Make sure the publisher has the required IAM permission, `PutObjectAcl` (and `PutObjectVersionAcl` if bucket versioning is enabled), either directly or via an assumed IAM Role (depending on your case). You can read more at link:https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-access-control.html[AWS S3 Access Permissions].

[[sec:gcs-repositories]]
== Google Cloud Storage repositories configuration

[[sub:gcs_configuration_properties]]
=== GCS configuration properties

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

`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]]
=== GCS 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)

[[sec:handling_credentials]]
== Handling credentials

Repository credentials should never be part of your build script but rather be kept external.
Gradle provides link:{javadocPath}/org/gradle/api/artifacts/repositories/AuthenticationSupported.html#credentials-java.lang.Class-[an API in artifact repositories]
that allows you to declare only the type of required credentials. Credential values are looked up from the <<build_environment.adoc#sec:gradle_configuration_properties,Gradle Properties>>
during the build that requires them.

For example, given repository configuration:

.Externalized repository credentials
====
include::sample[dir="samples/credentials-handling/publishing-credentials/groovy",files="build.gradle[tags=repositories]"]
include::sample[dir="samples/credentials-handling/publishing-credentials/kotlin",files="build.gradle.kts[tags=repositories]"]
====

The username and password will be looked up from `mySecureRepositoryUsername` and `mySecureRepositoryPassword` properties.

Note that the configuration property prefix - the identity - is determined from the repository name.
Credentials can then be provided in any of supported ways for Gradle Properties -
`gradle.properties` file, command line arguments, environment variables or a combination of those options.

Also, note that credentials will only be required if the invoked build requires them. If for example a project is configured
to publish artifacts to a secured repository, but the build does not invoke publishing task, Gradle will not require
publishing credentials to be present. On the other hand, if the build needs to execute a task that requires credentials
at some point, Gradle will check for credential presence first thing and will not start running any of the tasks
if it knows that the build will fail at a later point because of missing credentials.

Here is a link:../samples/sample_publishing_credentials.html[downloadable sample] that demonstrates the concept in more detail.

Lookup is only supported for credentials listed in the xref:#credentials_lookup_properties[xrefstyle=short].
[%header%autowidth,compact]
.Credentials that support value lookup and their corresponding properties
[[credentials_lookup_properties]]
|===
| Type | Argument | Base property name | Required?


.2+| `link:{javadocPath}/org/gradle/api/credentials/PasswordCredentials.html[PasswordCredentials]`
| `username`
| `Username`
| required

| `password`
| `Password`
| required

.3+| `link:{javadocPath}/org/gradle/api/credentials/AwsCredentials.html[AwsCredentials]`
| `accessKey`
| `AccessKey`
| required

| `secretKey`
| `SecretKey`
| required

| `sessionToken`
| `SessionToken`
| optional

.2+| `link:{javadocPath}/org/gradle/api/credentials/HttpHeaderCredentials.html[HttpHeaderCredentials]`
| `name`
| `AuthHeaderName`
| required

| `value`
| `AuthHeaderValue`
| required

|===
