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

file

none

http

username/password

Documentation

https

username/password

Documentation

sftp

username/password

Documentation

s3

access key/secret key/session token or Environment variables

Documentation

gcs

default application credentials sourced from well known files, Environment variables etc.

Documentation
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:

Example 1. Declaring HTTP-based Maven and Ivy Repositories
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
    }

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

    ivy {
        url "http://repo.mycompany.com/repo"
    }
}
Example 2. Declaring an SFTP Protocol for a Repository
build.gradle.kts
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"
        }
    }
}
build.gradle
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"
        }
    }
}
Example 3. Declaring an S3-Backed Maven and Ivy Repository
build.gradle.kts
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"
        }
    }
}
build.gradle
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"
        }
    }
}
Example 4. Declaring an S3-Backed Maven and Ivy Repository Using IAM
build.gradle.kts
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")
        }
    }
}
build.gradle
repositories {
    maven {
        url "s3://myCompanyBucket/maven2"
        authentication {
           awsIm(AwsImAuthentication) // load from EC2 role or env var
        }
    }

    ivy {
        url "s3://myCompanyBucket/ivyrepo"
        authentication {
           awsIm(AwsImAuthentication)
        }
    }
}
Example 5. Declaring a GCS-Backed Maven and Ivy Repository
build.gradle.kts
repositories {
    maven {
        url = uri("gcs://myCompanyBucket/maven2")
    }

    ivy {
        url = uri("gcs://myCompanyBucket/ivyrepo")
    }
}
build.gradle
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:

build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
    }
}
build.gradle
repositories {
    maven {
        url "http://repo.mycompany.com/maven2"
        credentials {
            username "user"
            password "password"
        }
    }
}

Digest Authentication

To configure a repository to use only DigestAuthentication:

build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<DigestAuthentication>("digest")
        }
    }
}
build.gradle
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:

build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<BasicAuthentication>("basic")
        }
    }
}
build.gradle
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:

build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials(HttpHeaderCredentials::class) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}
build.gradle
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:

build.gradle.kts
repositories {
    maven {
        name = "mySecureRepository"
        credentials(PasswordCredentials::class)
        // url = uri(<<some repository url>>)
    }
}
build.gradle
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?

PasswordCredentials

username

Username

required

password

Password

required

AwsCredentials

accessKey

AccessKey

required

secretKey

SecretKey

required

sessionToken

SessionToken

optional

HttpHeaderCredentials

name

AuthHeaderName

required

value

AuthHeaderValue

required