Gradle Publishing, Maven Publish, Ivy Publish, Signing, Metadata, and Repository Promotion: Configuration, Design Choices, and Tradeoffs

1. Maven versus Ivy is a consumer-contract decision

Do not start with “which Gradle plugin do I like?” Start with the consumers and repository manager. Maven-format repositories are the broad JVM interoperability default. Ivy remains useful where an organization deliberately operates Ivy metadata/layouts or needs Ivy-specific descriptor semantics. Applying both in one build can be useful for learning, but publishing two authoritative formats for the same product creates more metadata to govern.

2. Rich GMM versus Maven-compatible surface

Gradle consumers can use GMM to select variants with attributes/capabilities that a Maven POM cannot model. Maven consumers see the POM only. A library that exposes a plain Java API/runtime split usually maps cleanly. A library with custom variants, rich constraints, or Gradle-specific capabilities may not.

Publication warnings are therefore design feedback. Before suppressing one, compare the resolved graph from a clean Gradle consumer and a clean Maven consumer. If the graphs or available artifacts differ in a way that changes runtime behavior, the problem is not cosmetic.

3. Declared versus resolved dependency versions in POMs

By default, Maven Publish writes the versions declared by the build model. Gradle also supports versionMapping to publish resolved versions. That can be appropriate when a release is tested against locked/resolved versions or when rich Gradle constraints would map poorly to Maven.

publishing {
    publications {
        named<MavenPublication>("mavenJava") {
            versionMapping {
                usage("java-api") {
                    fromResolutionOf("runtimeClasspath")
                }
                usage("java-runtime") {
                    fromResolutionResult()
                }
            }
        }
    }
}

This is not universally “more reproducible.” It changes the public dependency contract. Review the generated POM diff and consumer graph before adopting it, especially for libraries whose API dependencies intentionally allow a range of compatible versions.

4. Direct-to-release versus stage-then-promote

Direct publication minimizes moving parts but gives the build job immediate authority over the release repository. Staging adds a state boundary: upload candidate bytes once, run verification against those exact bytes, then promote them without rebuilding. For commercial/internal repositories, that separation usually makes audit and rollback reasoning clearer.

5. Maven Local versus disposable file repo versus authoritative remote

Maven Local is a user cache and diagnostic bridge. A project-relative file repository is better for this course because its complete layout can be inspected, copied, hashed, and deleted as one lab artifact. Neither is a production release service. An authoritative repository adds access control, immutable releases, retention, replication, audit, and promotion semantics that Gradle alone does not provide.

6. Credentials and signing are separate authorization layers

Repository credentials answer “may this build write here?” A signing key answers “which cryptographic identity produced this signature?” The same CI job may possess both, but that does not make them the same secret. Least privilege often means a snapshot job can upload snapshots without a release signing key, while a protected release job receives both narrowly scoped repository write permission and signing capability.

Use repository-name-derived Gradle properties or provider-backed environment inputs. Never echo them. A Configuration Cache can serialize values used during configuration, so secret-handling policy must also consider cache storage and access controls.

7. Snapshots, releases, and mutable identity

A -SNAPSHOT version communicates changing development state in Maven conventions. A non-snapshot release should be immutable. Gradle can route repositories conditionally based on the project version, but routing is not an immutability guarantee; the destination repository must enforce the rule.

publishing {
    repositories {
        maven {
            name = "target"
            val releasesRepo = layout.buildDirectory.dir("repositories/releases")
            val snapshotsRepo = layout.buildDirectory.dir("repositories/snapshots")
            url = uri(if (version.toString().endsWith("SNAPSHOT")) snapshotsRepo else releasesRepo)
        }
    }
}

This snippet is safe only as a routing example. Production URLs, credentials, retention, and overwrite policy belong to repository governance.

8. Decision table

9. Worked scenario: one Gradle service team, two consumer ecosystems

A platform team owns a Java library consumed by 40 Gradle builds and 12 Maven builds. The Gradle consumers benefit from rich variants, but the Maven consumers must still receive a correct dependency graph. The team chooses Maven repository layout, publishes GMM alongside the POM, runs a Gradle consumer verification and Maven consumer verification against staging, signs the staged publication, and promotes the same coordinate tree. It does not create a Gradle-only release repository plus a separately rebuilt Maven artifact.

10. What this chapter does not configure

Gradle build logic can define publications, tasks, repository URLs, and credential interfaces. It does not administer Nexus/Artifactory retention, Maven Central namespaces, CI protected environments, organizational key custody, legal release approval, or vulnerability policy. Those systems consume the publication contract defined here.

Knowledge check

Official references and version notes

• Gradle 9.7.1 release notes — pinned Gradle baseline for this chapter.
• Publishing a project as a module — publication = artifacts + metadata, repository target, publish task, checksums, and signatures when configured.
• Maven Publish Plugin — MavenPublication, generated POM, repository tasks, Maven Local, version mapping, snapshot/release routing.
• Ivy Publish Plugin — IvyPublication, generated ivy.xml, Ivy repository layout and tasks.
• Gradle Module Metadata — variant-aware metadata, POM/Ivy mapping, publication warnings, validation, reproducibility.
• Signing Plugin — OpenPGP signatures, in-memory keys, GPG command integration, signing publications.
• Supported repository protocols and credentials — file/HTTP(S) transports, externalized credentials, repository-name-derived properties.
• Metadata formats — Gradle Module Metadata, Maven POM, Ivy descriptors and consumer behavior.
• Apache Maven releases history — Maven 3.9.16 is the current GA baseline used for the clean Maven consumer lane.
• Maven Compiler Plugin — pinned 3.15.0 compiler plugin for the Maven consumer fixture.

Version-sensitive behavior was rechecked against current Gradle and Apache Maven primary documentation on 2026-08-24. Mandatory publication uses only repository-owned files plus disposable file: repositories under the lab workspace. Maven Local, real credentials, real release repositories, hosted signing, Maven Central, Nexus/Artifactory administration, and CI-specific secret stores are not mandatory.