{"id":27646234,"url":"https://github.com/znsio/specmatic-gradle-plugin","last_synced_at":"2025-04-24T01:17:44.217Z","repository":{"id":279591068,"uuid":"939310801","full_name":"znsio/specmatic-gradle-plugin","owner":"znsio","description":"Plugin to standardize specmatic builds","archived":false,"fork":false,"pushed_at":"2025-04-22T12:42:37.000Z","size":426,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-22T12:44:49.469Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/znsio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-26T10:40:52.000Z","updated_at":"2025-04-22T12:42:40.000Z","dependencies_parsed_at":"2025-04-22T12:51:07.835Z","dependency_job_id":null,"html_url":"https://github.com/znsio/specmatic-gradle-plugin","commit_stats":null,"previous_names":["znsio/specmatic-gradle-plugin"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fspecmatic-gradle-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fspecmatic-gradle-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fspecmatic-gradle-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znsio%2Fspecmatic-gradle-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/znsio","download_url":"https://codeload.github.com/znsio/specmatic-gradle-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250540898,"owners_count":21447428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-24T01:17:43.721Z","updated_at":"2025-04-24T01:17:44.203Z","avatar_url":"https://github.com/znsio.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specmatic gradle convention plugin\n\n\u003e **NOTE:** This plugin contains plugin conventions for building specmatic tools. This is only to be used by the\n\u003e specmatic core\n\u003e team to build tools under the `io.specmatic` namespace.\n\nThe Specmatic Gradle Plugin provides an all-in-one solution for automating obfuscation, creating shadow JARs, and\npublishing artifacts to Maven repositories. By configuring the specmatic block, specmatic developers can streamline\ntheir build process without manually handling these steps. Ideal for simplifying deployment pipelines in JVM-based\nprojects.\n\n## Features\n\n1. Auto signing/publishing of artifacts\n - maven central\n - maven local\n - specmatic private repository (on github)\n - any other supported URLs/repositories\n2. License checks\n - Ensure that dependencies have a license that allows commecial use of specmatic software (i.e. no copy left\n licenses) without any incumberance.\n - Generate a license report that can be packaged in the distributable jar. This is legal requirement from licenses\n like Apache, BSD-3-Clause. These licenses have a clause that requires distributions of software to carry a notice,\n or attribution specified in the license.\n3. Pretty print test progress - uses https://github.com/radarsh/gradle-test-logger-plugin\n4. Publish artifacts and create GitHub releases\n - uses https://github.com/researchgate/gradle-release to create git tags\n - uses API to create a GitHub release\n5. Print task info and dependencies - uses https://gitlab.com/barfuin/gradle-taskinfo\n6. Print vulnerability scan reports - uses [osv-scanner](https://github.com/google/osv-scanner)\n7. Creates a `version.properties` and `VersionInfo.kt` file in the `${groupId}:${projectName}` package. This contains\n details like the version number, git sha. That may be useful for `--version` or just dumping the version at startup.\n8. Ensure that java and kotlin compilation is forced to a configured and consistent version across projects.\n9. Ensure artifacts are reproducible.\n10. Pretty print any `exec` or `javaexec` tasks, along with their outputs\n11. Auto-upgrade/migrated deprecated dependencies to newer dependencies.\n12. Better integration with sample repositories\n - Run a build against sample projects and validate changes.\n - Bummp version of dependency in sample project. Ensure that the appropriate jar is checked into the sample repo.\n13. Conflict detection and resolution using a combination of `io.fuchs.gradle.classpath-collision-detector`,\n `org.gradlex.jvm-dependency-conflict-detection`, `org.gradlex.jvm-dependency-conflict-resolution`.\n See https://github.com/REPLicated/classpath-collision-detector\n and https://gradlex.org/jvm-dependency-conflict-resolution/ for more details.\n\n## Requirements for using this plugin\n\n1. The following environment variables containing secrets are needed based on the\n requirements. [This script](https://github.com/znsio/specmatic-github-workflows/blob/main/bin/upload-secrets) will\n help you upload the relevant secrets by scanning your github workflows.\n\n | Variable(s) | Purpose | \n |---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n | **Maven Central** | |\n | `ORG_GRADLE_PROJECT_mavenCentralUsername` | Username for Maven Central |\n | `ORG_GRADLE_PROJECT_mavenCentralPassword` | Password for Maven Central |\n | **Signing** | |\n | `ORG_GRADLE_PROJECT_signingInMemoryKey` | GPG private key for signing (ascii armoured/base64 encoded, without the leading/trailing -----BEGIN/END lines) |\n | `ORG_GRADLE_PROJECT_signingInMemoryKeyId` | GPG key ID (last 8 chars of hex hex key without the leading `0x`) |\n | `ORG_GRADLE_PROJECT_signingInMemoryKeyPassword` | Passphrase for the GPG key |\n | **Specmatic Private Repo** | |\n | `ORG_GRADLE_PROJECT_specmaticPrivateUsername` | Username for Specmatic private repository |\n | `ORG_GRADLE_PROJECT_specmaticPrivatePassword` | Password for Specmatic private repository |\n | **Docker Hub** | |\n | No variables are needed, but you are required to perform a docker login yourself. The plugin will simply execute a `docker push` equivalent | |\n\n## Installation, usage and configuration\n\n1. Edit `build.gradle[.kts]`\n ```kotlin\n // in the root project only\n plugins {\n // version specified in settings.gradle \u0026 gradle.properties\n id(\"io.specmatic.gradle\")\n }\n ```\n\n2. Edit `settings.gradle[.kts]`\n ```kotlin\n pluginManagement {\n val specmaticGradlePluginVersion = settings.extra[\"specmaticGradlePluginVersion\"] as String\n plugins {\n id(\"io.specmatic.gradle\") version(specmaticGradlePluginVersion)\n }\n repositories {\n gradlePluginPortal()\n mavenCentral()\n mavenLocal()\n maven {\n name = \"specmaticPrivate\"\n url = uri(\"https://maven.pkg.github.com/znsio/specmatic-private-maven-repo\")\n credentials {\n username = listOf(\n settings.extra.properties[\"github.actor\"],\n System.getenv(\"SPECMATIC_GITHUB_USER\"),\n System.getenv(\"ORG_GRADLE_PROJECT_specmaticPrivateUsername\")\n ).firstNotNullOfOrNull { it }.toString()\n \n password = listOf(\n settings.extra.properties[\"github.token\"],\n System.getenv(\"SPECMATIC_GITHUB_TOKEN\"),\n System.getenv(\"ORG_GRADLE_PROJECT_specmaticPrivatePassword\")\n ).firstNotNullOfOrNull { it }.toString()\n }\n }\n\n }\n }\n ```\n\n3. Edit `gradle.properties` and add the plugin version\n ```properties\n specmaticGradlePluginVersion=\u003cPLUGIN_VERSION_HERE\u003e\n ```\n\n4. Add the following to your `build.gradle[.kts]` file\n ```kotlin\n specmatic {\n // Set the JVM version. Currently defaults to 17\n jvmVersion = JavaLanguageVersion.of(17)\n // Set the kotlin version to be used. Currently defaults to 1.9.25\n kotlinVersion = \"1.9.25\"\n // Set the kotlin compiler version. Currently defaults to 1.9\n kotlinApiVersion = KotlinVersion.KOTLIN_1_9\n // List of sample projects that need validation before release, and bumping post release\n downstreamDependentProjects = listOf(\"project1\", \"project2\")\n \n // replace certain dependencies with other dependencies\n versionReplacements = mapOf(\n \"org.example.foo:deprecated\" to \"org.example.foo:shiny-thing:1.2.3\"\n ) \n \n // Publish this to some repositories. Can be invoked multiple times\n publishTo(\"internalRepo\", \"https://internal.repo.url/repository/maven-releases/\")\n // Publish this to maven central. Only use this on open source code\n publishToMavenCentral()\n \n // Provide license details for any libraries that don't have license information in their POM.\n // if using groovy, you may need to prefix below lines with `it.XXX` instead\n licenseData {\n name = \"net.researchgate:gradle-release\"\n version = \"3.1.0\"\n projectUrl = \"https://github.com/researchgate/gradle-release\"\n license = \"MIT\"\n }\n \n `with\u003cCommercial|OSS\u003e\u003cLibrary|Application|ApplicationLibrary\u003e`(project(\":bar\")) {\n // The main class, if publishing an application variant\n mainClass = \"io.specmatic.ExampleApp\"\n \n // Create a GitHub release. Upload any files generated by specified tasks.\n githubRelease {\n addFile(\"sourcesJar\", \"foo-sources-${version}.jar\")\n }\n \n // Create a docker build/publish task. Pass any optional args to the docker build task. \n // The `--build-arg VERSION` is already passed as a default \n dockerBuild(\"--extra\", \"--docker\", \"--args\")\n \n // Obfuscation is enabled by default, but you may pass additional proguard args https://www.guardsquare.com/manual/configuration/usage\n obfuscate(\"-some-arg\")\n obfuscate(\"-more-args\", \"-some-more-args\")\n \n // Shadowing is enabled, but you pass any additional shadowing options - https://gradleup.com/shadow/\n shadow(prefix = \"specmatic_foo\") {\n minimize()\n // other options...\n }\n \n publish {\n // configure the pom and any other publication settings\n pom {\n name.set(\"Specmatic License Validation\")\n description.set(\"Specmatic License parsing and validation library\")\n url.set(\"https://specmatic.io\")\n }\n }\n }\n }\n ```\n\n5. Setup your `.gitignore`\n ```gitignore\n # Add the following to the .gitignore file\n gen-kt/\n gen-resources/\n ```\n\n6. Setup GitHub workflows. Best to copy/paste from existing workflows.\n\n## Handling conflict resolution\n\nTo work around the dependency hell problem where multiple dependencies have the same class, but different versions, you\ncan use the `detectCollisions` task to detect the collisions. This will print a report of all the dependencies that have\ncollisions, and their versions. Additionally, this plugin wraps the `org.gradlex.jvm-dependency-conflict-resolution`\nplugin that addresses conflict resolution for some [popular\ndependencies](https://gradlex.org/jvm-dependency-conflict-resolution/#all-capabilities). For other dependencies, you can\nuse the following snippet in your project:\n\n```kotlin\njvmDependencyConflicts {\n patch {\n // attach capabilities to multiple modules that offer the same capability\n module(\"org.example:old-name\") {\n addCapability(\"org.example:some-feature\")\n }\n\n module(\"org.example.somepackage:new-name\") {\n addCapability(\"org.example:some-feature\")\n }\n }\n\n // resolve the conflicts by selecting the highest version of the dependency\n conflictResolution {\n selectHighestVersion(\"org.example:some-feature\")\n }\n}\n```\n\n## Logging\n\nThis plugin ensures that the published application variants use slf4j and logback as the default logging mechanism.\nLogback dependencies are automatically added by the plugin. A default `logback.xml` is packaged that turns off all\nlogging by default. In addition, you should setup your application's `main()` function to call `JULForwarder.forward()`\nto setup appropriate forwarding of JUL logging to SLF4J.\n\n```kotlin\nimport io.specmatic.yourpackage.JULForwarder\n\nobject Main {\n @JvmStatic\n fun main(args: Array\u003cString\u003e) {\n JULForwarder.forward()\n // your application code here\n }\n}\n```\n\nYou may override the default logback configuration by creating a `logback.xml` file and executing the application via:\n\n```bash\njava -Dlogback.configurationFile=logback.xml -jar \u003cjar-file\u003e\n```\n\n## Available tasks\n\nHere is a list of available tasks\n\n| Task | Description |\n|------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Other checks** | |\n| `detectCollisions` | Detects dependency collisions and prints a report. |\n| **License Checks** | |\n| `checkLicense` | Check if License could be used |\n| `generateLicenseReport` | Generates license report for all dependencies of this project and its subprojects. |\n| **Publishing tasks** | |\n| `publishAllPublicationsToMavenCentralRepository` | Publishes all Maven publications produced by this project to the mavenCentral repository. |\n| `publishAllPublicationsToSpecmaticPrivateRepository` | Publishes all Maven publications produced by this project to the specmaticPrivate repository. |\n| `publishAllPublicationsToStagingRepository` | Publishes all Maven publications produced by this project to the staging repository. |\n| **Release tasks** | |\n| `afterReleaseBuild` | Runs immediately after the build when doing a release. Install task dependencies on this task to be executed after a release build. For e.g. `uploadArchives` |\n| `beforeReleaseBuild` | Runs immediately before the build when doing a release. Install task dependencies on this task to be execute before a release build. For e.g. `check` |\n| `publishToMavenCentral` | Publishes to a staging repository on Sonatype OSS. |\n| `release` | Verify project, release, and update version to next. |\n| **Vulnerability tasks** | |\n| `vulnScanSBOM` | Scan for and print vulnerabilities in just dependency tree. |\n| `vulnScanJar` | Scan for and print vulnerabilities by deep scanning inside each generated jar. |\n| `vulnScanDocker` | Scan for and Print vulnerabilities in docker image. |\n| **Docker tasks** | |\n| `dockerBuild` | Builds the docker image (for local use) |\n| `dockerBuildxPublish` | Builds and publishes `linux/amd64,linux/arm64` variants of the docker image | \n| **Downstream Project Validation** | |\n| `validateDownstreamProjects` | Validate downstream project(s) |\n| `bumpVersionsInDownstreamProjects` | Bump versions in downstream project(s) | \n| `fetchArtifactsInDownstreamProjects` | Fetch artifacts downstream project(s) | \n| **Internal tasks** | |\n| `createGithubRelease` | Create a Github release. This is already wired up when publishing a release. |\n| `cyclonedxBom` | Generates a CycloneDX compliant Software Bill of Materials (SBOM). |\n\n## Available distribution flavours and the artifacts they generate\n\n| Generated artifact(s) | Obfuscated | Fat/Shadowed/Shaded | Has dependencies in POM | Javadoc/Source Jars | Is executable | Purpose |\n|:--------------------------------------------------------------------------------|:----------:|:-------------------:|:-----------------------:|:-------------------:|:-------------:|---------------------------------------------------------------------------------|\n| **OSSLibraryConfig** | | | | | | |\n| `${groupId}:${projectId}` | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | \u0026#x2705; | \u0026#x274C; | Publishing a library (specmatic-junit5, for e.g.) |\n| **OSSApplicationConfig** | | | | | | |\n| `${groupId}:${projectId}` | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x2705; | \u0026#x2705; | Publishing an application (specmatic-executable, for e.g.) |\n| **OSSApplicationLibraryConfig** | | | | | | |\n| `${groupId}:${projectId}` | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | \u0026#x2705; | \u0026#x2705; | Use the application code as a library (specmatic-executable, for e.g.) |\n| `${groupId}:${projectId}-all` | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x2705; | \u0026#x2705; | Publishing an application (specmatic-executable-all, for e.g.) |\n| **CommercialLibraryConfig** | | | | | | |\n| `${groupId}:${projectId}` | \u0026#x2705; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | Publish a commercial library, for use in other modules (license core, for e.g.) |\n| `${groupId}:${projectId}-all-debug` | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | For local debugging, above jar, but unobfuscated |\n| `${groupId}:${projectId}-min` | \u0026#x2705; | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | Obfuscated, but has dependencies in POM, for local debugging | |\n| `${groupId}:${projectId}-core-dont-use-this-unless-you-know-what-you-are-doing` | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | Original jar + original deps in the POM, for local debugging |\n| **CommercialApplicationConfig** | \u0026#x2705; | \u0026#x2705; | | | | |\n| `${groupId}:${projectId}` | \u0026#x2705; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | Publish this for end user consumption |\n| `${groupId}:${projectId}-all-debug` | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | For local debugging |\n| **CommercialApplicationAndLibraryConfig** | \u0026#x2705; | \u0026#x2705; | | | | |\n| `${groupId}:${projectId}` | \u0026#x2705; | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | Publish this for end user consumption as as library |\n| `${groupId}:${projectId}-all` | \u0026#x2705; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | Publish this for end user consumption as an executable |\n| `${groupId}:${projectId}-all-debug` | \u0026#x274C; | \u0026#x2705; | \u0026#x274C; | \u0026#x274C; | \u0026#x2705; | For local debugging |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznsio%2Fspecmatic-gradle-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fznsio%2Fspecmatic-gradle-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznsio%2Fspecmatic-gradle-plugin/lists"}