Supported Protocols
Gradle supports a variety of transport protocols for Maven and Ivy repositories.
Supported transport protocols
These protocols determine how Gradle communicates with the repositories to resolve dependencies.
Type | Credential types | Link |
---|---|---|
|
none |
|
|
username/password |
|
|
username/password |
|
|
username/password |
|
|
access key/secret key/session token or Environment variables |
|
|
default application credentials sourced from well known files, Environment variables etc. |
Usernames and passwords should never be stored in plain text in your build files. Instead, store credentials in a local gradle.properties file or use an open-source Gradle plugin for encrypting and consuming credentials, such as the credentials plugin.
|
The transport protocol is specified as part of the repository URL.
Below are examples of how to declare repositories using various protocols:
repositories {
maven {
url = uri("http://repo.mycompany.com/maven2")
}
ivy {
url = uri("http://repo.mycompany.com/repo")
}
}
repositories {
maven {
url "http://repo.mycompany.com/maven2"
}
ivy {
url "http://repo.mycompany.com/repo"
}
}
repositories {
maven {
url = uri("sftp://repo.mycompany.com:22/maven2")
credentials {
username = "user"
password = "password"
}
}
ivy {
url = uri("sftp://repo.mycompany.com:22/repo")
credentials {
username = "user"
password = "password"
}
}
}
repositories {
maven {
url "sftp://repo.mycompany.com:22/maven2"
credentials {
username "user"
password "password"
}
}
ivy {
url "sftp://repo.mycompany.com:22/repo"
credentials {
username "user"
password "password"
}
}
}
repositories {
maven {
url = uri("s3://myCompanyBucket/maven2")
credentials(AwsCredentials::class) {
accessKey = "someKey"
secretKey = "someSecret"
// optional
sessionToken = "someSTSToken"
}
}
ivy {
url = uri("s3://myCompanyBucket/ivyrepo")
credentials(AwsCredentials::class) {
accessKey = "someKey"
secretKey = "someSecret"
// optional
sessionToken = "someSTSToken"
}
}
}
repositories {
maven {
url "s3://myCompanyBucket/maven2"
credentials(AwsCredentials) {
accessKey "someKey"
secretKey "someSecret"
// optional
sessionToken "someSTSToken"
}
}
ivy {
url "s3://myCompanyBucket/ivyrepo"
credentials(AwsCredentials) {
accessKey "someKey"
secretKey "someSecret"
// optional
sessionToken "someSTSToken"
}
}
}
repositories {
maven {
url = uri("s3://myCompanyBucket/maven2")
authentication {
create<AwsImAuthentication>("awsIm") // load from EC2 role or env var
}
}
ivy {
url = uri("s3://myCompanyBucket/ivyrepo")
authentication {
create<AwsImAuthentication>("awsIm")
}
}
}
repositories {
maven {
url "s3://myCompanyBucket/maven2"
authentication {
awsIm(AwsImAuthentication) // load from EC2 role or env var
}
}
ivy {
url "s3://myCompanyBucket/ivyrepo"
authentication {
awsIm(AwsImAuthentication)
}
}
}
repositories {
maven {
url = uri("gcs://myCompanyBucket/maven2")
}
ivy {
url = uri("gcs://myCompanyBucket/ivyrepo")
}
}
repositories {
maven {
url "gcs://myCompanyBucket/maven2"
}
ivy {
url "gcs://myCompanyBucket/ivyrepo"
}
}
Configuring authentication schemes
HTTP(S) authentication schemes configuration
When configuring a repository that uses HTTP or HTTPS transport protocols, several authentication schemes are available. By default, Gradle attempts to use all schemes supported by the Apache HttpClient library. However, you may want to explicitly specify which authentication schemes should be used when interacting with a remote server. When explicitly declared, only those specified schemes will be used.
Basic authentication
You can specify credentials for Maven repositories secured by basic authentication using PasswordCredentials:
repositories {
maven {
url = uri("http://repo.mycompany.com/maven2")
credentials {
username = "user"
password = "password"
}
}
}
repositories {
maven {
url "http://repo.mycompany.com/maven2"
credentials {
username "user"
password "password"
}
}
}
Digest Authentication
To configure a repository to use only DigestAuthentication:
repositories {
maven {
url = uri("https://repo.mycompany.com/maven2")
credentials {
username = "user"
password = "password"
}
authentication {
create<DigestAuthentication>("digest")
}
}
}
repositories {
maven {
url 'https://repo.mycompany.com/maven2'
credentials {
username "user"
password "password"
}
authentication {
digest(DigestAuthentication)
}
}
}
Supported Authentication Schemes
- BasicAuthentication
-
Basic access authentication over HTTP. Credentials are sent preemptively.
- DigestAuthentication
-
Digest access authentication over HTTP.
- HttpHeaderAuthentication
-
Authentication based on a custom HTTP header, such as private tokens or OAuth tokens.
Using preemptive authentication
By default, Gradle submits credentials only when a server responds with an authentication challenge (HTTP 401). However, some servers might respond with a different code (e.g., GitHub returns a 404) that could cause dependency resolution to fail. In such cases, you can configure Gradle to send credentials preemptively by explicitly using the BasicAuthentication scheme:
repositories {
maven {
url = uri("https://repo.mycompany.com/maven2")
credentials {
username = "user"
password = "password"
}
authentication {
create<BasicAuthentication>("basic")
}
}
}
repositories {
maven {
url 'https://repo.mycompany.com/maven2'
credentials {
username "user"
password "password"
}
authentication {
basic(BasicAuthentication)
}
}
}
Using HTTP header authentication
For Maven repositories that require token-based, OAuth2, or other HTTP header-based authentication, you can use HttpHeaderCredentials and HttpHeaderAuthentication:
repositories {
maven {
url = uri("http://repo.mycompany.com/maven2")
credentials(HttpHeaderCredentials::class) {
name = "Private-Token"
value = "TOKEN"
}
authentication {
create<HttpHeaderAuthentication>("header")
}
}
}
repositories {
maven {
url "http://repo.mycompany.com/maven2"
credentials(HttpHeaderCredentials) {
name = "Private-Token"
value = "TOKEN"
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
AWS S3 repositories configuration
When configuring a repository that uses AWS S3, several options and settings are available.
S3 configuration properties
The following system properties can be used to configure interactions with S3 repositories:
org.gradle.s3.endpoint
-
Overrides the AWS S3 endpoint when using a non-AWS, S3 API-compatible storage service.
org.gradle.s3.maxErrorRetry
-
Specifies the maximum number of retry attempts when the S3 server responds with an HTTP 5xx status code. The default value is 3 if not specified.
S3 URL formats
S3 URLs must use the 'virtual-hosted-style' format:
s3://<bucketName>[.<regionSpecificEndpoint>]/<s3Key>
Example: s3://myBucket.s3.eu-central-1.amazonaws.com/maven/release
-
myBucket
: The AWS S3 bucket name. -
s3.eu-central-1.amazonaws.com
: The optional region-specific endpoint. -
/maven/release
: The AWS S3 key (a unique identifier for an object within a bucket).
S3 proxy settings
A proxy for S3 can be configured using the following system properties:
-
For HTTPS:
-
https.proxyHost
-
https.proxyPort
-
https.proxyUser
-
https.proxyPassword
-
http.nonProxyHosts
(NOTE: this is not a typo.) *For HTTP (if org.gradle.s3.endpoint is set with an HTTP URI): -
http.proxyHost
-
http.proxyPort
-
http.proxyUser
-
http.proxyPassword
-
http.nonProxyHosts
-
S3 V4 Signatures (AWS4-HMAC-SHA256)
Some S3 regions (e.g., eu-central-1
in Frankfurt) require that all HTTP requests are signed using AWS’s signature version 4.
It is recommended to specify S3 URLs containing the region-specific endpoint when using buckets that require V4 signatures:
s3://somebucket.s3.eu-central-1.amazonaws.com/maven/release
If the region-specific endpoint is not specified for buckets requiring V4 Signatures, Gradle defaults to the us-east-1
region and will issue a warning:
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 such buckets results in:
-
Increased network traffic: Three round-trips to AWS per file upload/download instead of one.
-
Slower builds: Due to increased network latency.
-
Higher transmission failure rates: Due to additional network overhead.
S3 Cross Account Access
In organizations with multiple AWS accounts (e.g., one per team), the bucket owner may differ from the artifact publisher or consumers.
To ensure consumers can access the artifacts, the bucket owner must grant the appropriate access.
Gradle automatically applies the bucket-owner-full-control
Canned ACL to uploaded objects.
Ensure the publisher has the required IAM permissions (PutObjectAcl
and PutObjectVersionAcl
if bucket versioning is enabled), either directly or through an assumed IAM Role. For more details, see AWS S3 Access Permissions.
Google Cloud Storage repositories configuration
When configuring a repository that uses Google Cloud Storage (GCS), several configuration options and settings are available.
GCS configuration properties
You can use the following system properties to configure interactions with GCS repositories:
org.gradle.gcs.endpoint
-
Overrides the Google Cloud Storage endpoint, useful when working with a storage service compatible with the GCS API but not hosted on Google Cloud Platform.
org.gradle.gcs.servicePath
-
Specifies the root service path from which the GCS client builds requests, with a default value of
/
.
GCS URL formats
GCS URLs use a 'virtual-hosted-style' format and must adhere to the following structure:
gcs://<bucketName>/<objectKey>
-
<bucketName>
: The name of the Google Cloud Storage bucket. -
<objectKey>
: The unique identifier for an object within a bucket.
Example: gcs://myBucket/maven/release
-
myBucket
: The bucket name. -
/maven/release
: The GCS object key.
Handling credentials
Repository credentials should never be hardcoded in your build script but kept external. Gradle provides an API in artifact repositories that allows you to declare the type of credentials required, with their values being looked up from Gradle properties during the build.
For example, consider the following repository configuration:
repositories {
maven {
name = "mySecureRepository"
credentials(PasswordCredentials::class)
// url = uri(<<some repository url>>)
}
}
repositories {
maven {
name = 'mySecureRepository'
credentials(PasswordCredentials)
// url = uri(<<some repository url>>)
}
}
In this example, the username and password are automatically looked up from properties named mySecureRepositoryUsername
and mySecureRepositoryPassword
.
Configuration property prefix
The configuration property prefix, known as the identity, is derived from the repository name.
Credentials can be provided through any of the supported Gradle property mechanisms: gradle.properties
file, command-line arguments, environment variables, or a combination of these.
Conditional credential requirement
Credentials are only required when the build process needs them. For example, if a project is configured to publish artifacts to a secured repository, but the publishing task isn’t invoked, Gradle won’t require the credentials. However, if a task requiring credentials is part of the build process, Gradle will check for their presence before running any tasks to prevent build failures due to missing credentials.
Supported credential types
Lookup is only supported for the credential types listed in the table below:
Type | Argument | Base property name | Required? |
---|---|---|---|
|
|
required |
|
|
|
required |
|
|
|
required |
|
|
|
required |
|
|
|
optional |
|
|
|
required |
|
|
|
required |