search

jfrog / artifactory-gradle-plugin

JFrog Gradle plugin for Build Info extraction and Artifactory publishing.
Apache License 2.0
20 stars 15 forks source link
artifactory gradle gradle-plugin java jfrog

readme

# 🐸 Artifactory Gradle Plugin 🐘
[![Test](https://github.com/jfrog/artifactory-gradle-plugin/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/jfrog/artifactory-gradle-plugin/actions/workflows/test.yml?query=branch%3Amain) [![Test](https://github.com/jfrog/artifactory-gradle-plugin/actions/workflows/gradle.yml/badge.svg?branch=main)](https://github.com/jfrog/artifactory-gradle-plugin/actions/workflows/gradle.yml??query=branch%3Amain) [![Scanned by Frogbot](https://raw.github.com/jfrog/frogbot/master/images/frogbot-badge.svg)](https://github.com/jfrog/frogbot#readme)

Table of Contents

📚 Overview

The Gradle Artifactory Plugin provides tight integration with Gradle. All that is needed is a simple modification of your build.gradle script file with a few configuration parameters, and you can deploy your build artifacts and build information to Artifactory.

The plugin adds the artifactoryPublish task for each project, in the 'publishing' group. The task performs the following actions on the project and its submodules:

  1. Extracting the build-info file located in the root project. This file contains comprehensive information about the build, such as its configuration, dependencies, and other relevant details.
  2. Deploying both the generated artifacts and the build-info file to your Artifactory repository. This ensures that the artifacts, which are the output of the build process, and the accompanying build-info file are stored and organized in your Artifactory repository for easy access and management.

NOTE: The minimum supported Gradle version to use this plugin is v6.8.1

🚚 Migrating from Version 4 to Version 5 of the Plugin --- #### Version 5 of the Gradle Artifactory Plugin includes the following breaking changes compared to version 4 * The minimum version of Gradle required to use this plugin has been upgraded to version 6.9. * The below convention attributes have been removed: | Attribute | Migration action | |:---------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | parent | No longer supported. | | resolve | To define the Artifactory resolution repositories for your build, declare the repositories under the repositories section as described [here](https://docs.gradle.org/current/userguide/declaring_repositories.html#declaring-repositories). |

📦 Installation

Step 1 - Add the plugin to your project --- Add the following snippet to your build script:
Kotlin Format ```kotlin plugins { id("com.jfrog.artifactory") version "5.+" } ```
Groovy Format ```groovy plugins { id "com.jfrog.artifactory" version "5.+" } ```
---
Step 2 - Configure the plugin with your Artifactory --- To configure the plugin with your Artifactory, add the following basic snippet to your project root build script, and make the necessary adjustments based on your platform information:
Kotlin Format ```kotlin configure { publish { // Define the Artifactory URL for publishing artifacts contextUrl = "http://127.0.0.1:8081/artifactory" // Define the project repository to which the artifacts will be published repository { // Set the Artifactory repository key repoKey = "libs-snapshot-local" // Specify the publisher username username = project.property("artifactory_user") as String // Provide the publisher password password = project.property("artifactory_password") as String } // Include all configured publications for all the modules defaults { publications("ALL_PUBLICATIONS") } } } ```
Groovy Format ```groovy artifactory { publish { // Define the Artifactory URL for publishing artifacts contextUrl = 'http://127.0.0.1:8081/artifactory' // Define the project repository to which the artifacts will be published repository { // Set the Artifactory repository key repoKey = 'libs-snapshot-local' // Specify the publisher username username = "${artifactory_user}" // Provide the publisher password password = "${artifactory_password}" } // Include all configured publications for all the modules defaults { publications('ALL_PUBLICATIONS') } } } ```
### ⚙️ Advance Configurations For advanced configurations and finer control over the plugin's operations, refer to the following documentation that outlines all the available configuration options. These options allow you to customize the behavior of the plugin according to your specific needs.
🏢🔧 Artifactory Configurations --- The provided code snippet showcases the configuration options for the Artifactory plugin. It demonstrates how to fine-tune the plugin's behavior to meet specific project requirements, access the Artifactory instance to which the artifacts will be published, and configure other global settings such as Proxy and Build-Info extraction configurations.
Kotlin Format ```kotlin configure { publish { // Define the Artifactory URL for publishing artifacts contextUrl = "http://127.0.0.1:8081/artifactory" // Define the project repository to which the artifacts will be published repository { // Option 1 - Define the Artifactory repository key repoKey = "libs-snapshot-local" // Option 2 - Specify release and snapshot repositories; let the plugin decide to which one to publish // releaseRepoKey = "libs-release-local" // snapshotRepoKey = "libs-snapshot-local" // Specify the publisher username username = project.property("artifactory_user") as String // Provide the publisher password password = project.property("artifactory_password") as String // This is an optional section (relevant only when publishIvy = true) for configuring Ivy publication. ivy { ivyLayout = "[organization]/[module]/ivy-[revision].xml" artifactLayout = "[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]" // Convert any dots in an [organization] layout value to path separators, similar to Maven's groupId-to-path conversion. True if not specified mavenCompatible = true } } // Optionally, you can specify global configurations. These configurations will be added for all projects instead of configuring them for each project. defaults { // artifactoryPublish task attributes... } // (default: true) Publish the generated build-info file to Artifactory publishBuildInfo = false // (default: 3) Number of threads that will work and deploy artifacts to Artifactory forkCount = 5 } // Optionally, configure and control the information and attributes of the generated build-info file. // Alternatively, you can configure the attributes by using the `clientConfig.info` object. buildInfo { // Set specific build and project information for the build-info buildName = "new-strange-name" buildNumber = "" + Random(System.currentTimeMillis()).nextInt(20000) project = "project-key" // Add a dynamic property to the build-info addEnvironmentProperty("test.adding.dynVar", Date().toString()) // Generate a copy of the build-info.json file in the following path generatedBuildInfoFilePath = "/Users/gradle-example-publish/myBuildInfoCopy.json" // Generate a file with all the deployed artifacts' information in the following path deployableArtifactsFilePath = "/Users/gradle-example-publish/myArtifactsInBuild.json" } // Optionally, you can use and configure your proxy information to use in the task. // Alternatively, you can configure the attributes by using the clientConfig.proxy object. proxy { host = "ProxyHost" port = 60 username = "ProxyUserName" password = "ProxyPassword" } // (default: 300 seconds) Artifactory's connection timeout (in seconds). clientConfig.timeout = 600 // (default: 0 retries) Artifactory's connection retires clientConfig.connectionRetries = 4 // (default: false) Set to true to skip TLS certificates verification. clientConfig.insecureTls = false // (default: false) Set to true to include environment variables while running the tasks clientConfig.isIncludeEnvVars = true // Set patterns of environment variables to include/exclude while running the tasks clientConfig.envVarsExcludePatterns = "*password*,*secret*" clientConfig.envVarsIncludePatterns = "*not-secret*" } ```
Groovy Format ```groovy artifactory { publish { // Define the Artifactory URL to publish the artifacts contextUrl = 'http://127.0.0.1:8081/artifactory' // Define the project repository to which the artifacts will be published repository { // Option 1 - Define the Artifactory repository key repoKey = 'libs-snapshot-local' // Option 2 - Specify release and snapshot repositories; let the plugin decide to which one to publish // releaseRepoKey = 'libs-release-local' // snapshotRepoKey = 'libs-snapshot-local' // The publisher username username = "${artifactory_user}" // The publisher password password = "${artifactory_password}" // This is an optional section (relevant only when publishIvy = true) for configuring Ivy publication. ivy { ivyLayout = '[organization]/[module]/ivy-[revision].xml' artifactLayout = '[organization]/[module]/[revision]/[module]-[revision](-[classifier]).[ext]' //Convert any dots in an [organization] layout value to path separators, similar to Maven's groupId-to-path conversion. True if not specified mavenCompatible = true } } // Optionally, you can specify global configurations. These configurations will be added for all projects instead of configuring them for each project. defaults { // artifactoryPublish task attributes... } // (default: true) Publish the generated build-info file to Artifactory publishBuildInfo = false // (default: 3) Number of threads that will work and deploy artifacts to Artifactory forkCount = 5 } // Optionally, configure and control the information and attributes of the generated build-info file. // Alternatively, you can configure the attributes by using the `clientConfig.info` object. buildInfo { // Set specific build and project information for the build-info setBuildName('new-strange-name') setBuildNumber('' + new Random(System.currentTimeMillis()).nextInt(20000)) setProject('project-key') // Add a dynamic property to the build-info addEnvironmentProperty('test.adding.dynVar', new java.util.Date().toString()) // Generate a copy of the build-info.json file in the following path setGeneratedBuildInfoFilePath("/Users/gradle-example-publish/myBuildInfoCopy.json") // Generate a file with all the deployed artifacts' information in the following path setDeployableArtifactsFilePath("/Users/gradle-example-publish/myArtifactsInBuild.json") } // Optionally, you can use and configure your proxy information to use in the task. // Alternatively, you can configure the attributes by using the clientConfig.proxy object. proxy { host = "ProxyHost" port = 60 username = "ProxyUserName" password = "ProxyPassword" } // (default: 300 seconds) Artifactory's connection timeout (in seconds). clientConfig.timeout = 600 // (default: 0 retries) Artifactory's connection retires clientConfig.setConnectionRetries(4) // (default: false) Set to true to skip TLS certificates verification. clientConfig.setInsecureTls(false) // (default: false) Set to true to include environment variables while running the tasks clientConfig.setIncludeEnvVars(true) // Set patterns of environment variables to include/exclude while running the tasks clientConfig.setEnvVarsExcludePatterns('*password*,*secret*') clientConfig.setEnvVarsIncludePatterns('*not-secret*') } ```
---
📋🔧 Project Publication Configurations --- The `artifactoryPublish` task configuration allows you to customize the task operation and behavior for a specific project, in addition to the global defaults. The global defaults configuration applies to the project and its submodules, while the artifactoryPublish configuration allows you to define additional settings specifically for the project. When using artifactoryPublish, you have the flexibility to configure additional values without overriding the global defaults. This means that the project can have its own specific configuration in addition to the common settings applied globally.
Kotlin Format ```kotlin tasks.named("artifactoryPublish") { // Specify what publications to include when collecting artifacts for publishing to Artifactory publications( // Publication can be specified as an Object publishing.publications["ivyJava"], // Publication can be specified as a String "mavenJava", // If this plugin constant string is specified, the plugin will try to apply all the known publications "ALL_PUBLICATIONS" ) // Optionally, configure properties to be attached to the published artifacts. setProperties(mapOf( "key1" to "value1", "key2" to "value2" )) // (default: false) Skip this task for the project (don't include its artifacts when publishing) skip = true // (default: true) Publish generated artifacts to Artifactory, can be specified as boolean/string setPublishArtifacts(false) // (default: true) Publish generated POM files to Artifactory, can be specified as boolean/string setPublishPom(false) // (default: true) Publish generated Ivy descriptor files to Artifactory, can be specified as boolean/string setPublishIvy(false) // (default: 'GRADLE') Set a custom module type for the published module in the build-info. // Acceptable values: 'GENERIC', 'MAVEN', 'GRADLE', 'IVY', 'DOCKER', 'NUGET', 'NPM', 'GO', 'PYPI', 'CPP' setModuleType("GRADLE") } ```
Groovy Format ```groovy artifactoryPublish { publications('ALL_PUBLICATIONS') properties = ['qa.level': 'basic', 'dev.team': 'core'] // In Groovy format, properties can also be defined with a closure in the format: configName artifactSpec, key1:val1, key2:val2 properties { simpleFile '**:**:**:*@*', simpleFile: 'only on settings file' } skip = true publishArtifacts = false publishPom = false publishIvy = false moduleType = 'GRADLE' } ```

🚀 Usage

To deploy the project artifacts and build info to Artifactory, execute the following Gradle task

./gradlew artifactoryPublish

💡 Examples

The following are links to the build scripts of different types of projects that are configured to use the plugin.

Multi Modules Project (Groovy)

Sample project that uses the Gradle Artifactory Plugin with Gradle Publications.

Multi Modules Project (Kotlin)

Sample project that configures the Gradle Artifactory Plugin with the Gradle Kotlin DSL.

We highly recommend also using our gradle project examples as a reference when configuring your build scripts.

🐞 Reporting Issues

We highly recommend running Gradle with the -d option to get useful and readable debug information if something goes wrong with your build.

Please help us improve the plugin by reporting any issues you encounter.

🫱🏻‍🫲🏼 Contributions

We welcome pull requests from the community. To help us improve this project, please read our Contribution guide.