Artifactory Gradle Plugin

Introduction

The Gradle Artifactory Plugin provides tight integration with Gradle. You can deploy your build artifacts and build information to JFrog Artifactory by adding a few configuration parameters to your build.gradle script.

The plugin adds three Gradle tasks.

TaskScopePurpose
artifactoryPublishPer projectCollects deploy details from publications.
extractModuleInfoPer projectProduces moduleInfo.json from collected details.
artifactoryDeployRoot project onlyDeploys artifacts and build information to JFrog Artifactory.

Execution flow: artifactoryPublish then extractModuleInfo then artifactoryDeploy (root).

  • Plugin ID: com.jfrog.artifactory
  • Supported Gradle: The minimum version enforced by code is 6.8.1. Gradle 8 or above is recommended. The plugin is primarily tested with Gradle 9+.
  • Java: The plugin compiles to Java 8. Gradle 9 itself requires Java 17 or later.

Installation

Plugin Declaration

Kotlin:

plugins {
    id("com.jfrog.artifactory") version "6.+"
}

Groovy:

plugins {
    id "com.jfrog.artifactory" version "6.+"
}

Multi-Project Setup

Apply the plugin with apply false in the root build script, then apply it in allprojects or selected subprojects. The plugin auto-applies itself to the root project when you apply it to a subproject. It isn't applied to buildSrc.

Kotlin:

plugins {
    id("com.jfrog.artifactory") apply false
}

allprojects {
    apply(plugin = "com.jfrog.artifactory")
}

Groovy:

plugins {
    id 'com.jfrog.artifactory' apply false
}

allprojects {
    apply plugin: 'com.jfrog.artifactory'
}

Quick Start

The minimum configuration requires contextUrl, repository.repoKey, repository.username, and repository.password.

Kotlin:

configure<ArtifactoryPluginConvention> {
    publish {
        contextUrl = "http://127.0.0.1:8081/artifactory"
        repository {
            repoKey = "libs-snapshot-local"
            username = project.property("artifactory_user") as String
            password = project.property("artifactory_password") as String
        }
        defaults {
            publications("ALL_PUBLICATIONS")
        }
    }
}

Groovy:

artifactory {
    publish {
        contextUrl = 'http://127.0.0.1:8081/artifactory'
        repository {
            repoKey = 'libs-snapshot-local'
            username = "${artifactory_user}"
            password = "${artifactory_password}"
        }
        defaults {
            publications('ALL_PUBLICATIONS')
        }
    }
}

To deploy, run the following command.

./gradlew artifactoryPublish

Configuration Reference

Top-Level artifactory Block

The following table describes the top-level properties you can configure in the artifactory block.

Block or PropertyPurposeDefault
publish { }Publishing configuration.--
buildInfo { }Build information metadata.--
proxy { }HTTP proxy settings.--
clientConfig.timeoutConnection timeout in seconds.300
clientConfig.connectionRetriesNumber of connection retries.0
clientConfig.insecureTlsSkip TLS certificate verification.false
clientConfig.isIncludeEnvVarsInclude environment variables in build information.false
clientConfig.envVarsIncludePatternsComma-separated include patterns for environment variables.--
clientConfig.envVarsExcludePatternsComma-separated exclude patterns for environment variables.--

Kotlin:

configure<ArtifactoryPluginConvention> {
    publish { /* ... */ }
    buildInfo { /* ... */ }
    proxy { /* ... */ }

    clientConfig.timeout = 600
    clientConfig.connectionRetries = 4
    clientConfig.insecureTls = false
    clientConfig.isIncludeEnvVars = true
    clientConfig.envVarsExcludePatterns = "*password*,*secret*"
    clientConfig.envVarsIncludePatterns = "*not-secret*"
}

Groovy:

artifactory {
    publish { /* ... */ }
    buildInfo { /* ... */ }
    proxy { /* ... */ }

    clientConfig.timeout = 600
    clientConfig.setConnectionRetries(4)
    clientConfig.setInsecureTls(false)
    clientConfig.setIncludeEnvVars(true)
    clientConfig.setEnvVarsExcludePatterns('*password*,*secret*')
    clientConfig.setEnvVarsIncludePatterns('*not-secret*')
}

publish Block

The following table describes the properties available in the publish block.

PropertyPurposeDefault
contextUrlJFrog Artifactory base URL.--
repository { }Target repository settings.--
repository.repoKeySingle repository key.--
repository.releaseRepoKeyRelease repository key.--
repository.snapshotRepoKeySnapshot repository key.--
repository.usernamePublisher username.--
repository.passwordPublisher password.--
repository.ivy { }Ivy layout configuration (when publishIvy = true).--
repository.ivy.ivyLayoutIvy descriptor layout pattern.--
repository.ivy.artifactLayoutIvy artifact layout pattern.--
repository.ivy.mavenCompatibleConvert dots to path separators in [organization].true
defaults { }Default configuration applied to all artifactoryPublish tasks.--
publishBuildInfoPublish build information to JFrog Artifactory.true
forkCountNumber of parallel deploy threads.3

Kotlin:

publish {
    contextUrl = "http://127.0.0.1:8081/artifactory"
    repository {
        repoKey = "libs-snapshot-local"
        // Or use release and snapshot repositories:
        // releaseRepoKey = "libs-release-local"
        // snapshotRepoKey = "libs-snapshot-local"
        username = project.property("artifactory_user") as String
        password = project.property("artifactory_password") as String
        ivy {
            ivyLayout = "[organization]/[module]/ivy-[revision].xml"
            artifactLayout = "[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]"
            mavenCompatible = true
        }
    }
    defaults {
        publications("mavenJava", "ivyJava")
    }
    publishBuildInfo = true
    forkCount = 5
}

Groovy:

publish {
    contextUrl = 'http://127.0.0.1:8081/artifactory'
    repository {
        repoKey = 'libs-snapshot-local'
        username = "${artifactory_user}"
        password = "${artifactory_password}"
        ivy {
            ivyLayout = '[organization]/[module]/ivy-[revision].xml'
            artifactLayout = '[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]'
            mavenCompatible = true
        }
    }
    defaults {
        publications('mavenJava', 'ivyJava')
    }
    publishBuildInfo = true
    forkCount = 5
}

buildInfo Block

The following table describes the properties available in the buildInfo block.

PropertyPurpose
buildNameOverride build name. Default is the root project name.
buildNumberOverride build number. Default is an epoch-millisecond timestamp.
projectJFrog Artifactory project key.
addEnvironmentProperty(key, value)Add a custom environment property.
generatedBuildInfoFilePathPath for an extra build information JSON copy.
deployableArtifactsFilePathPath for deployed artifacts JSON.

Kotlin:

buildInfo {
    buildName = "my-build"
    buildNumber = "" + Random(System.currentTimeMillis()).nextInt(20000)
    project = "project-key"
    addEnvironmentProperty("test.adding.dynVar", Date().toString())
    generatedBuildInfoFilePath = "/path/to/myBuildInfoCopy.json"
    deployableArtifactsFilePath = "/path/to/myArtifactsInBuild.json"
}

Groovy:

buildInfo {
    setBuildName('my-build')
    setBuildNumber('' + new Random(System.currentTimeMillis()).nextInt(20000))
    setProject('project-key')
    addEnvironmentProperty('test.adding.dynVar', new java.util.Date().toString())
    setGeneratedBuildInfoFilePath('/path/to/myBuildInfoCopy.json')
    setDeployableArtifactsFilePath('/path/to/myArtifactsInBuild.json')
}

You can also control build name and number through gradle.properties.

buildInfo.build.name=my-super-cool-build
buildInfo.build.number=r9001

proxy Block

The following table describes the properties available in the proxy block.

PropertyPurpose
hostProxy hostname.
portProxy port.
usernameProxy username.
passwordProxy password.
noProxyHosts to bypass the proxy.
proxy {
    host = 'www.somehost.org'
    port = 8080
    username = 'userid'
    password = 'password'
    noProxy = 'internal.myorg.com'
}

For dependency resolution through a proxy, use the standard Gradle proxy configuration in gradle.properties.

systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password

artifactoryPublish Task and defaults Block

The defaults block inside publish applies configuration to every artifactoryPublish task. You can also configure a specific project's task directly.

The following table describes the properties available on the task or in the defaults block.

PropertyPurposeDefault
publications(...)Publications to include.--
publications("ALL_PUBLICATIONS")Include all known publications.--
propertiesMap of artifact properties.--
properties { configName artifactSpec, key:val }Scoped properties (Groovy closure).--
skipSkip this project entirely.false
publishArtifactsPublish artifacts.true
publishPomPublish POM files.true
publishIvyPublish Ivy descriptors.true
moduleTypeModule type in build information.GRADLE

The following moduleType values are valid: GENERIC, MAVEN, GRADLE, IVY, DOCKER, NUGET, NPM, GO, PYPI, and CPP.

Kotlin (per-project task):

tasks.named<ArtifactoryTask>("artifactoryPublish") {
    publications(
        publishing.publications["ivyJava"],
        "mavenJava",
        "ALL_PUBLICATIONS"
    )
    setProperties(mapOf("key1" to "value1", "key2" to "value2"))
    skip = false
    setPublishArtifacts(true)
    setPublishPom(true)
    setPublishIvy(true)
    setModuleType("GRADLE")
}

Groovy (per-project task):

artifactoryPublish {
    publications('ALL_PUBLICATIONS')
    properties = ['qa.level': 'basic', 'dev.team': 'core']
    properties {
        simpleFile '**:**:**:*@*', simpleFile: 'only on settings file'
    }
    skip = false
    publishArtifacts = true
    publishPom = true
    publishIvy = true
    moduleType = 'GRADLE'
}

Artifact notation for scoped properties: group:module:version:classifier@type (for example, org.example:my-artifact:1.0.0:test@jar). Wildcards: * for any characters, ? for a single character. Use all as the configuration name to apply to all publications or configurations.

Publications

ALL_PUBLICATIONS

Set publications("ALL_PUBLICATIONS") to publish artifacts from every publication defined in the project.

Default Publications

When you don't specify any publications and the project has the publishing extension applied, the plugin automatically looks for mavenJava, mavenJavaPlatform, mavenWeb, and ivyJava.

Maven and Ivy Side by Side

The following example shows how to configure both Maven and Ivy publications in the same project.

publishing {
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
        ivyJava(IvyPublication) {
            from components.java
        }
    }
}

artifactory {
    publish {
        defaults {
            publications('mavenJava', 'ivyJava')
        }
    }
}

Artifact Properties

Simple Map

artifactoryPublish {
    properties = ['qa.level': 'basic', 'q.os': 'win32, deb, osx']
}

Scoped Properties (Groovy Closure)

artifactoryPublish {
    properties {
        foo '*:*:*:*@*', platform: 'linux', 'win64'
        mavenJava 'org.jfrog:*:*:*@*', key1: 'val1'
        all 'org.jfrog:shared:1.?:*@*', key2: 'val2', key3: 'val3'
    }
}

The syntax follows this format: configName 'group:module:version:classifier@type', key1:'value1', key2:'value2'

  • configName: A publication name, or all to apply to all publications.
  • The artifact filter supports * (any characters) and ? (single character).

Use Cases and Examples

The following table lists available example projects.

Use CaseExample ProjectNotes
Multi-module Maven + Ivy (Groovy)src/functionalTest/resources/gradle-example-publish/Uses mavenJava and ivyJava publications.
Multi-module (Kotlin DSL)src/functionalTest/resources/gradle-kts-example-publish/Same configuration in Kotlin.
Android (APK and AAR)src/functionalTest/resources/gradle-android-example/Custom publications per module.
Skip root or specific modulesAll examplesUses artifactoryPublish.skip = true.
Per-project publicationssrc/functionalTest/resources/gradle-android-example/Uses artifactoryPublish { publications(...) }.
Proxy with noProxy bypasssrc/functionalTest/resources/gradle-example-publish/build.gradleUses proxy { host, port, noProxy }.
Default BOMsrc/functionalTest/resources/gradle-example-default-bom/Java Platform (BOM) publishing.
Custom BOMsrc/functionalTest/resources/gradle-example-custom-bom/Custom mavenJavaPlatform.
Version catalogsrc/functionalTest/resources/gradle-example-version-catalog/Producer and consumer setup.
Gradle plugin publishingsrc/functionalTest/resources/gradle-plugin/Uses ALL_PUBLICATIONS.

Sub-Project Control

The plugin supports hierarchical configuration. Define artifactory { } in the root project and all subprojects inherit it. Any subproject can override the publish or repository configuration.

Set artifactoryPublish.skip = true on a project to exclude it from publishing.

./gradlew clean api:artifactoryPublish shared:artifactoryPublish

CI Integration

Init Script Mode

When driven from a CI server (for example, the Jenkins Artifactory Plugin or JFrog CLI), the plugin is applied through an init script (initscripttemplate.gradle). This init script does the following:

  • Applies ArtifactoryPluginSettings to the settings, which adds JFrog Artifactory as a resolution repository.
  • Applies ArtifactoryPlugin to all projects.
  • Sets setCiServerBuild() on every artifactoryPublish task to enable CI mode.

In CI mode, publications are read from the ArtifactoryClientConfiguration.publisher.publications property, which is populated from build-info.properties generated by JFrog CLI or the Jenkins plugin.

Resolver from Properties

When a build-info.properties file is present (set through the BUILDINFO_PROPFILE or PROP_PROPS_FILE environment variable), the plugin reads contextUrl and repoKey from it and configures JFrog Artifactory as the resolution repository, replacing other remote Maven and Ivy repositories.

Migration and Compatibility

Version 6 (Current)

Version 6 of the Gradle Artifactory Plugin introduces support for Gradle version 9. The code and documentation for Version 6 are available at the Gradle Artifactory Plugin GitHub repository.

Note: For Gradle version 6.8.1 through 8 (inclusive), use version 5. For Gradle 9, use version 6.

Version 6 includes the following breaking changes:

  • The plugin compiles to Java 8. Gradle 9 itself requires Java 17 or later.
  • The minimum Gradle version enforced by the plugin is 6.8.1. Gradle 8 or above is recommended. The plugin is primarily tested with Gradle 9+.
  • The web-archive convention attribute has been removed. The plugin now produces both JAR and WAR archives.

Version 5

This major release completely rewrote the plugin code from Groovy to Java.

Version 5 includes the following breaking changes:

  • The minimum supported Gradle version has been increased to 6.8.1. The legacy archive configurations are no longer supported.
  • The parent closure in the artifactory convention is no longer compatible or supported.

For project examples that use the Gradle Artifactory Plugin, see the functional test resources.

Migrate from Version 4 to Version 5 or 6

The following Version 4 features have been removed or relocated.

Version 4 FeatureStatus in Version 5 and 6
publishConfigs()Removed. Use publications() instead.
mavenDescriptorRemoved.
ivyDescriptorRemoved.
publishBuildInfo in defaultsMoved to publish { publishBuildInfo = ... }.
contextUrl on artifactoryPublish taskRemoved from task. Set on publish { contextUrl = ... }.
clientConfig.publisher.* on taskRemoved from task. Set on artifactory { publish { repository { ... } } }.
clientConfig.proxy.*Replaced with proxy { } closure.
clientConfig.info.*Replaced with buildInfo { } closure.
parent closureRemoved.

Troubleshooting

The following table describes common problems and their solutions.

ProblemSolution
Build fails with Gradle version error.The plugin requires Gradle 6.8.1 or later. Update Gradle or use an older plugin version. The error message includes the minimum supported version.
No artifacts published.Verify that publications() is configured and the named publications exist in the project.
Invalid properties specification error.Use the format configName 'group:module:version:classifier@type', key1:'value1', key2:'value2'.
You need detailed logs.Run Gradle with -d for debug output.
Proxy doesn't work for deployment.Configure the proxy { } block inside artifactory { }.
Proxy doesn't work for resolution.Proxy for dependency resolution uses the standard Gradle configuration in gradle.properties (systemProp.http.proxyHost and related properties). The plugin doesn't intervene in resolution.

Gaps and Known Discrepancies

The following table lists known discrepancies between the documentation and the source code.

ItemNotes
Gradle versionCode enforces 6.8.1 minimum. The README and documentation say 8+.
includePatterns and excludePatternsAvailable in the build information PublisherHandler but not exposed in the plugin DSL.
filterExcludedArtifactsFromBuildAvailable in PublisherHandler but not exposed in the plugin DSL.
minChecksumDeploySizeKbAvailable in PublisherHandler (default 10) but not exposed in the plugin DSL.
timeout defaultDocumented as 300 seconds. No explicit 300-second default in ArtifactoryClientConfiguration. The default may come from the underlying HTTP client.
connectionRetries defaultDocumented as zero. No explicit default in code.

Appendix: Gradle Artifactory Plugin Version 4 (Legacy)

Note: The entire Version 4 section describes features and DSL syntax that apply only to Version 4 of the plugin. If you use Version 5 or 6, use the configuration reference in the sections above instead.

The Gradle Artifactory Plugin allows you to deploy your build artifacts and build information to JFrog Artifactory and also to resolve your build dependencies from JFrog Artifactory. The minimum supported Gradle version is 4.10.

Download and Install Gradle Artifactory Plugin Version 4

The following snippet shows how to add the plugin to your build script for all Gradle versions.

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "org.jfrog.buildinfo:build-info-extractor-gradle:4.+"
  }
}
apply plugin: "com.jfrog.artifactory"

The following snippet shows how to add the plugin for Gradle 2.1 and above.

// Replace <plugin version> with the version of the Gradle Artifactory Plugin.
plugins {
  id "com.jfrog.artifactory" version "<plugin version>"
}

Tip: The plugins notation can't be used for applying the plugin to subprojects when used from the root build script.

Configure Gradle Artifactory Plugin Version 4

This section describes how to configure the Gradle Artifactory Plugin Version 4.

For project examples that use the Gradle Artifactory Plugin, see the Gradle project examples.

Use Artifactory Plugin DSL (Version 4)

You configure the Gradle Artifactory plugin using its own Convention DSL inside the build.gradle script of your root project.

The recommended approach is to also use the project examples as a reference when configuring the DSL in your build scripts.

Tip: Mandatory items within the relevant context are prefixed with +. All other items are optional.

Dependency Resolution

repositories {
        mavenCentral()
        maven {
                url "http://repo.myorg.com/artifactory/libs-releases"
                credentials {
                        username = "resolver"
                password = "resolverPaS*"
                }
        }

        ivy {
                url "http://localhost:8081/artifactory/ivy-releases"
                layout "pattern", {
                ivy "[organization]/[module]/[revision]/ivy.xml"
                artifact "[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]"
                m2compatible = true
        }
        }
}

Note: For more information, see the Gradle documentation for different ways to configure your repositories.

Artifacts and Build Information Publication (Version 4)

artifactory {
  contextUrl = 'http://repo.myorg.com/artifactory'
  publish {
    contextUrl = 'http://repo.myorg.com/artifactory'
    repository {
      repoKey = 'integration-libs'
      username = 'deployer'
      password = 'deployerPaS*'
      ivy {
        ivyLayout = '[organization]/[module]/[revision]/[type]s/ivy-[revision].xml'
        artifactLayout = '[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]'
        mavenCompatible = true
      }
    }
    defaults {
        publications ('ivyJava','mavenJava','foo')
        publishConfigs('archives', 'published')
        properties = ['qa.level': 'basic', 'q.os': 'win32, deb, osx']
        properties {
            foo '*:*:*:*@*', platform: 'linux', 'win64'
            mavenJava 'org.jfrog:*:*:*@*', key1: 'val1'
            all 'org.jfrog:shared:1.?:*@*', key2: 'val2', key3: 'val3'
        }
        publishBuildInfo = true
        publishArtifacts = true
        publishPom = true
        publishIvy = true
    }
  }
  clientConfig.setIncludeEnvVars(true)
  clientConfig.setEnvVarsExcludePatterns('*password*,*secret*')
  clientConfig.setEnvVarsIncludePatterns('*not-secret*')
  clientConfig.info.addEnvironmentProperty('test.adding.dynVar',new java.util.Date().toString())
  clientConfig.info.setBuildName('new-strange-name')
  clientConfig.info.setBuildNumber('' + new java.util.Random(System.currentTimeMillis()).nextInt(20000))
  clientConfig.info.setProject('project-key')
  clientConfig.timeout = 600
  clientConfig.setInsecureTls(false)
}

Control Environment Variable Exposure (Version 4)

As shown in the example, you can control which environment variables are exposed in clientConfig.setIncludeEnvVars using clientConfig.setEnvVarsExcludePatterns and clientConfig.setEnvVarsIncludePatterns. These calls specify which environment variables to exclude or include using a comma-separated list of expressions. The expressions can use a star (*) wildcard to match multiple environment variables.

Use Old Gradle Publishing Mechanism (Version 4 Only)

If you're using the old Gradle publishing mechanism, replace the defaults closure with the following one.

defaults {
        publishConfigs ('a','b','foo')
        mavenDescriptor = '/home/froggy/projects/proj-a/fly-1.0.pom'
        ivyDescriptor = 'fly-1.0-ivy.xml'
        properties = ['qa.level': 'basic', 'q.os': 'win32, deb, osx']
        properties {
            foo '*:*:*:*@*', platform: 'linux', 'win64'
            archives 'org.jfrog:*:*:*@*', key1: 'val1'
            all 'org.jfrog:shared:1.?:*@*', key2: 'val2', key3: 'val3'
        }
        publishBuildInfo = true
        publishArtifacts = true
        publishPom = true
        publishIvy = false
    }

Artifactory Project Publish Task (Version 4)

The Artifactory Publishing Plugin creates an artifactoryPublish Gradle task for each project the plugin is applied to. The task is configured by the publish closure of the plugin.

You can configure the project-level task directly with the artifactoryPublish closure, which uses identical syntax to that of the publish.defaults closure.

artifactoryPublish {
    skip = false
    contextUrl = 'http://repo.myorg.com/artifactory'
    publications ('a','b','c')
    properties = ['qa.level': 'basic', 'q.os': 'win32, deb, osx']
    properties {
        c '**:**:**:*@*', cProperty: 'only in c'
    }
    clientConfig.publisher.repoKey = 'integration-libs'
    clientConfig.publisher.username = 'deployer'
    clientConfig.publisher.password = 'deployerPaS'

    clientConfig.publisher.setExcludePatterns("*artifacts-to-exclude-1*,*artifacts-to-exclude-2*")
    clientConfig.publisher.setFilterExcludedArtifactsFromBuild(true)

    clientConfig.publisher.minChecksumDeploySizeKb = 10
}

Control Publication in Sub-Projects with Gradle (Version 4)

You can define different publication configurations for subprojects. You can also define the configuration once for the whole project by defining the artifactory closure only in the root project. The plugin also lets you disable publication for a submodule.

When you define the configuration anywhere in the hierarchy, all subprojects beneath it inherit the configuration and can override it whether it's defined in the root or in a subproject.

Each subproject can override the publish closure, the repositories closure, or both.

The following example shows how to override publication only.

artifactory {
        publish {
                contextUrl = 'http://localhost:8081/artifactory'
                repository {
                        repoKey = "libs-snapshot-local"
                        username = "user"
                        password = "pass"
                }
        }
}

For build information to be published, you must define a publish closure in the root project.

Use the artifactoryPublish.skip flag to deactivate analysis and publication.

To activate the artifactoryPublish Gradle task manually for each project, run the following command.

./gradlew clean api:artifactoryPublish shared:artifactoryPublish

Use HTTP Proxy with Gradle Artifactory Plugin Version 4

For deployment, add the following fields to the artifactory closure in the build.gradle file.

artifactory {
  ...
  clientConfig.proxy.host = 'www.somehost.org'
  clientConfig.proxy.port = '8080'
  clientConfig.proxy.username = 'userid'
  clientConfig.proxy.password = 'password'
}

The Artifactory Gradle plugin doesn't intervene in the Gradle dependency resolution process. To resolve Gradle dependencies through a proxy, use the regular Gradle proxy configuration in the gradle.properties file.

systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password