Artifacts validator Gradle plugin

Introduction

The artifacts validator plugin checks that a project publishes exactly the Maven artifacts you expect.

It supports two related workflows:

• Validate the publications declared in the current Gradle build without building the artifacts themselves.
• Validate the contents of a standalone local Maven repository containing built and published artifacts.

Requirements

• Minimum supported Gradle version: 8.5

Applying the plugin

This is a settings plugin, so apply it in settings.gradle.kts:

plugins {
    id("org.jetbrains.kotlinx.artifacts-validator-plugin") version "0.0.2"
}

Projects whose publications should be tracked must apply maven-publish (only Maven publications are checked).

Registered tasks

The plugin registers these tasks in each and every project:

• checkArtifacts: validates current maven-publish publications against artifact rule files.
• dumpArtifacts: generates artifact dump files from current maven-publish publications.

And it also registers the following task to the root project:

• validateLocalMavenRepo: validates an arbitrary local Maven repository against rule files.

Settings extension

The plugin adds an artifactsValidation extension to Gradle settings.

If you use Gradle 8.8 or newer, you can access it in settings.gradle.kts using a type safe accessor:

artifactsValidation {
    dumpFileRootDirectory.set(layout.rootDirectory.dir("artifacts"))
}

For older Gradle versions, a more verbose syntax is required:

extensions.configure<kotlinx.validation.artifacts.ArtifactsValidatorPluginSettingsExtension>("artifactsValidation") {
    dumpFileRootDirectory.set(layout.rootDirectory.dir("artifacts"))
}

Supported properties:

• dumpFileRootDirectory: directory where dump files are stored. Default: artifacts

Depending on these settings, files containing lists of artifacts will have the following names:

<dumpFileRootDirectory>/<project-name>.txt

Typical workflow

1. Apply the plugin in settings.gradle.kts.
2. Configure your publications with maven-publish.
3. Generate expected artifact dumps with ./gradlew dumpArtifacts.
4. Commit the generated dump files.
5. Run ./gradlew checkArtifacts to ensure publications still match.

Using checkArtifacts

checkArtifacts compares the publications currently declared in the build to the configured dump files.

Example:

Configure Maven publications using maven-publish plugin.

Then run:

./gradlew checkArtifacts

Using dumpArtifacts

dumpArtifacts writes rule files describing the publications found in the current build.

With default settings it writes:

artifacts/<project-name>.txt

Using validateLocalMavenRepo

validateLocalMavenRepo scans a Maven repository directory or ZIP archive and compares its contents to one or more rule files.

Basic example:

./gradlew validateLocalMavenRepo \
  --artifacts-dir=build/test-repo \
  --artifacts-list=artifacts/artifacts.txt:0.0.1

ZIP input works as well:

./gradlew validateLocalMavenRepo \
  --artifacts-zip=build/test-repo.zip \
  --artifacts-list=artifacts/artifacts.txt:0.0.1

Multiple rule files with independent expected versions are supported:

./gradlew validateLocalMavenRepo \
  --artifacts-dir=build/test-repo \
  --artifacts-list=artifacts/artifacts-core.txt:0.0.1 \
  --artifacts-list=artifacts/artifacts-ext.txt:2025a-0.0.1

For multi-module projects where artifacts share the same version, you can specify a path to a directory with artifacts lists instead of individual files:

./gradlew validateLocalMavenRepo \
  --artifacts-dir=build/test-repo \
  --artifacts-list=artifacts/:0.0.1

Additional options:

• --require-signatures: require an .asc file for every artifact
• --require-checksums=MD5,SHA1,SHA256,SHA512: require checksum files for the listed algorithms
• exactly one of --artifacts-dir or --artifacts-zip must be supplied

You can inspect the full CLI help with:

./gradlew -q help --task validateLocalMavenRepo

Artifact rules format

Artifact rule files describe expected artifacts using lines in this format:

<groupId>:<artifactId>/<comma separated list of classifier.extension pairs>

Examples:

org.jetbrains.kotlinx:kotlinx-io-core/.jar,.pom,.module,sources.jar,javadoc.jar,kotlin-tooling-metadata.json

Equivalent verbose form:

org.jetbrains.kotlinx:kotlinx-io-core/.jar
org.jetbrains.kotlinx:kotlinx-io-core/.pom
org.jetbrains.kotlinx:kotlinx-io-core/.module
org.jetbrains.kotlinx:kotlinx-io-core/sources.jar
org.jetbrains.kotlinx:kotlinx-io-core/javadoc.jar
org.jetbrains.kotlinx:kotlinx-io-core/kotlin-tooling-metadata.json

If an artifact has no classifier, the classifier part is empty, such as .jar or .pom.

See Maven artifact properties for the terminology.

Validation behavior

checkArtifacts:

• Reads configured dump files.
• Collects artifacts declared by current maven-publish publications.
• Fails if expected and actual artifact sets differ.

validateLocalMavenRepo:

• Reads all provided rule files.
• Associates each rule file with the version supplied in --artifacts-list=<file>:<version>.
• Scans the target repository.
• Fails if the repository contains invalid Maven-layout files.
• Fails if expected and actual artifact sets differ.
• Optionally verifies presence of signature and checksum sidecar files.

Signature and checksum validation check only file presence, not file contents.