Maven and Gradle

A maven repository stores artifacts in the standard Maven 2 layout. Maven, Gradle and any other Maven-compatible client can read from it. Gradle plugins use the same repository: a plugin and its marker artifact are ordinary Maven files.

Repository URL

Every maven repository has one URL:

https://repo.example.com/maven/<repo>

Replace repo.example.com with the server URL and <repo> with the repository name. The examples below use the repository name releases.

The server answers GET and HEAD for reads and PUT for uploads. You do not call PUT yourself. The Gradle plugin and the Maven extension open a publish session and add the credentials for you. See Publishing overview.

Read credentials

A repository can allow anonymous reads. If it does not, send HTTP Basic credentials:

• a user name and password, or
• any user name with a read token as the password.

Use a read token in builds. A read token cannot publish. A password cannot publish either: every write needs a publish session.

Read from Maven

Dependencies

pom.xml

<repositories>
  <repository>
    <id>telesphorepo</id>
    <url>https://repo.example.com/maven/releases</url>
  </repository>
</repositories>

Private repository

Add a <server> with the same <id> to ~/.m2/settings.xml:

~/.m2/settings.xml

<settings>
  <servers>
    <server>
      <id>telesphorepo</id>
      <username>ci</username>
      <password>READ_TOKEN</password>
    </server>
  </servers>
</settings>

Deploy target

pom.xml

<distributionManagement>
  <repository>
    <id>telesphorepo</id>
    <url>https://repo.example.com/maven/releases</url>
  </repository>
</distributionManagement>

Deploys need the Telesphorepo extension. See Maven extension.

Caution

Maven 3.8.1 and later block http:// repositories on hosts other than localhost. Serve the repository over HTTPS.

Read from Gradle

Dependencies

build.gradle.kts

repositories {
    maven {
        url = uri("https://repo.example.com/maven/releases")
    }
}

Plugins

Add the repository to pluginManagement to resolve plugins from it:

settings.gradle.kts

pluginManagement {
    repositories {
        maven {
            url = uri("https://repo.example.com/maven/releases")
        }
        gradlePluginPortal()
    }
}

Private repository

Add credentials to the maven block, in repositories or in pluginManagement.repositories:

build.gradle.kts

repositories {
    maven {
        url = uri("https://repo.example.com/maven/releases")
        credentials {
            username = "ci"
            password = providers.environmentVariable("TELESPHOREPO_READ_TOKEN").get()
        }
    }
}

The user name can be any value when the password is a read token.

Publishing

build.gradle.kts

publishing {
    repositories {
        maven {
            name = "telesphorepo"
            url = uri("https://repo.example.com/maven/releases")
        }
    }
}

Do not add credentials. The settings plugin adds them. See Gradle plugin.

Note

Set isAllowInsecureProtocol = true inside the maven block only for a plain http:// URL, such as a local test server.

Overwrite rules

The server decides on every PUT:

Case	Result
New path	201 Created
Same bytes as the stored file	200 OK (a safe retry)
Different bytes, release version	409 Conflict
Different bytes, mutable path	200 OK and the file is replaced
File larger than max_upload_bytes	413

A release file never changes. To fix a bad release, publish a new version.

The mutable paths are:

• maven-metadata.xml and its checksum files (maven-metadata.xml*)
• any file under a directory whose name ends in -SNAPSHOT

Snapshots

A version that ends in -SNAPSHOT is mutable. You can publish it again and again. Maven and Gradle update maven-metadata.xml for you, and the server accepts the new copy.

You can publish snapshots and releases to the same repository, or use separate repositories. Both work. The overwrite rule follows the path, not the repository.

Gotchas

• Writes need a publish session. A password or a read token on a PUT gets 401. The error message names the Publishing page of the server.
• A mirrored repository is read only. A repository that mirrors a Nexus source refuses uploads until you cut over. See Nexus migration.
• Private repository, wrong name. An unknown repository name and a missing login both answer 401 for anonymous callers, so repository names do not leak. Check the name and the token.
• Redirects on S3. When the server uses S3 storage with s3.redirect on, a GET answers 302 to a presigned URL. Maven and Gradle follow it. HEAD is never redirected. See Storage.