# Supported Protocols

version 9.7.0-rc-3

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 provide the credentials via environment variables.

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 = providers.environmentVariable("username").orNull
                password = providers.environmentVariable("password").orNull
            }
        }

        ivy {
            url = uri("sftp://repo.mycompany.com:22/repo")
            credentials {
                name = "mySecureCompanyRepository"
                credentials(PasswordCredentials::class)
            }
        }
    }

build.gradle

    repositories {
        maven {
            url = "sftp://repo.mycompany.com:22/maven2"
            credentials {
                username = providers.environmentVariable("username").orNull
                password = providers.environmentVariable("password").orNull
            }
        }

        ivy {
            url = "sftp://repo.mycompany.com:22/repo"
            credentials {
                name = "mySecureCompanyRepository"
                credentials(PasswordCredentials)
            }
        }
    }

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 = providers.environmentVariable("username").orNull
                password = providers.environmentVariable("password").orNull
            }
        }
    }

build.gradle

    repositories {
        maven {
            url = "http://repo.mycompany.com/maven2"
            credentials {
                username = "user"
                password = "password"
            }
        }
    }

| When the Configuration Cache is enabled, credentials passed to a repository may be consumed at configuration time and become part of the cached build configuration. The resolved values are captured in the encrypted cache entry on disk. See Handling of Credentials and Secrets for the implications and recommended ways to store sensitive values.

#### Digest Authentication

To configure a repository to use only DigestAuthentication:

build.gradle.kts

    repositories {
        maven {
            url = uri("https://repo.mycompany.com/maven2")
            credentials {
                username = providers.environmentVariable("username").orNull
                password = providers.environmentVariable("password").orNull
            }
            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 = providers.environmentVariable("username").orNull
                password = providers.environmentVariable("password").orNull
            }
            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