{"id":22969281,"url":"https://github.com/simonhauck/gradle-release-plugin","last_synced_at":"2026-01-27T23:38:05.031Z","repository":{"id":239831336,"uuid":"755359042","full_name":"simonhauck/gradle-release-plugin","owner":"simonhauck","description":"A gradle plugin to automate your releases with Git.","archived":false,"fork":false,"pushed_at":"2024-05-22T17:34:16.000Z","size":1502,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-23T01:05:21.932Z","etag":null,"topics":["automation","git","gradle","gradle-plugin","release","release-automation"],"latest_commit_sha":null,"homepage":"https://github.com/simonhauck/gradle-release-plugin","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/simonhauck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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}},"created_at":"2024-02-10T00:48:48.000Z","updated_at":"2024-05-27T21:27:41.212Z","dependencies_parsed_at":"2024-05-27T21:44:24.742Z","dependency_job_id":null,"html_url":"https://github.com/simonhauck/gradle-release-plugin","commit_stats":null,"previous_names":["simonhauck/gradle-release-plugin"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhauck%2Fgradle-release-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhauck%2Fgradle-release-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhauck%2Fgradle-release-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonhauck%2Fgradle-release-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonhauck","download_url":"https://codeload.github.com/simonhauck/gradle-release-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246763843,"owners_count":20829798,"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":["automation","git","gradle","gradle-plugin","release","release-automation"],"created_at":"2024-12-14T21:35:14.419Z","updated_at":"2026-01-27T23:38:05.025Z","avatar_url":"https://github.com/simonhauck.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gradle Release Plugin\n\n[![Main](https://github.com/simonhauck/gradle-release-plugin/actions/workflows/on-main-push.yml/badge.svg)](https://github.com/simonhauck/gradle-release-plugin/actions/workflows/on-main-push.yml)\n[![Plugin Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/io/github/simonhauck/release/io.github.simonhauck.release.gradle.plugin/maven-metadata.xml?label=Gradle%20Plugin%20Portal\u0026colorB=brightgreen\u0026logo=gradle)](https://plugins.gradle.org/plugin/io.github.simonhauck.release)\n\nThe Gradle Release Plugin is a small tool designed to streamline and automate the release process for your Gradle\nprojects. The plugin will increment the version number, commit, tag and push the changes to the git repository and\nincrease the version again to a new snapshot version. It is inspired by\nthe [researchgate/release-plugin](https://github.com/researchgate/gradle-release), but\naddresses some of its shortcomings and provides additional functionalities.\n\n- **Multiple Release Types**: You can either directly specify the release version or use a simplified API and just\n  select the release type. Let the plugin do the rest.\n- **Adaptable Release Workflow**: The plugin offers flexibility by allowing you to incorporate custom tasks into the\n  release process to make it fit your specific project requirements\n- **Composite Build Support**: This plugin can be applied to projects with a composite build, addressing\n  an [issue](https://github.com/researchgate/gradle-release/issues/304)\n  found in the above-mentioned project.\n- **Configuration Cache Support**: This plugin can be used in projects where the configuration cache is\n  enabled [issue](https://github.com/researchgate/gradle-release/issues/346)\n\n## How to use the plugin\n\nHere is quick guide on how to get started using this plugin.\n\n### Prerequisites\n\n1. Git: In order to perform the different git operations the plugin requires git to be available in the path\n2. Version properties file: A file with a containing a key `version` and as value the current project version (like in\n   this [example](version.properties)). By default, the plugin will look for the value in a `version.properties` or\n   `gradle.properties` file. You can change the name and location with the configuration.\n3. Gradle: Version 8.2 or higher\n4. Java: Version 17 or higher\n\n### Configuration\n\nIn your `build.gradle.kts` file, apply the plugin and configure it as shown below:\n\n```kotlin\n// build.gradle.kts\nimport io.github.simonhauck.release.version.api.Version\n\nplugins {\n    id(\"io.github.simonhauck.release\") version \"\u003cthe-current-version\u003e\"\n}\n\nrelease {\n    // Here you can apply additional configuration\n}\n\n// If you want to set the version in you gradle project you can use this helper method\nversion = Version.fromPropertiesFile(layout.projectDirectory.file(\"version.properties\"))\n```\n\nThe plugin provides sensible defaults for the release process. If you want to customize the release process, have a look\nat the [configuration options](#configuration-options).\n\n### Trigger a release\n\nIf you have a project layout as described in the [prerequisites](#prerequisites) section, you can already start\nreleasing. The plugin provides several ways to set the new version.\n\nYou can set the release and post-release version explicitly with the following gradle command:\n\n```shell\n./gradlew release -PreleaseVersion=1.0.0 -PpostReleaseVersion=1.0.1-SNAPSHOT\n```\n\nAlternately, if you have a [semver](https://semver.org/) compatible version you can use the simplified API:\n\n```shell\n# Current version: 1.0.0, release-type=major -\u003e Release Version: 2.0.0, Post Release Version: 2.0.1-SNAPSHOT\n./gradlew release -PreleaseType=\u003crelease-type\u003e\n\n# Or \n\n# Current version: 1.0.0, release-type=major, preReleaseType=RC -\u003e Release Version: 2.0.0-RC1, Post Release Version: 1.0.0\n./gradlew release -PreleaseType=\u003crelease-type\u003e -PpreReleaseType=\u003cpre-release-type\u003e\n```\n\nReplace the _release-type_ with ``major``, ``minor`` or ``patch``. This will determine the version automatically.\nThe _pre-release-type_ is an optional string (e.g. ALPHA). If set, the plugin will automatically apply a counter based\non the existing git tags and set the post release version back to the current project version, so when you create the \"\nfinal\" release, you can select the same release type - just without the _pre-release-type_.\n\n### What does the plugin do?\n\nThe plugins checks, that you do not have uncommited file changes and do not depend on snapshot or pre-release versions.\nIf these checks pass, the plugin will create two commits. The first commit will contain the release version. This commit\nwill be\ntagged and pushed. Afterward, a second commit with the post release version will be performed and pushed. Typically, you\nwant to set the next snapshot version here.\nIf you are running this in an CI environment, these commits can trigger a new build where you can perform\nadditional release logic. An example for GitHub actions is shown [here](#example-with-github-actions).\n\nIf your want to test your configuration locally without bothering your team with constant commits, you can\ndisable pushes with the shown configuration. It will still generate commits and tags, but you can delete them locally\nafterward.\n\n```kotlin\n// build.gradle.kts\nrelease {\n    disablePush = true\n}\n```\n\n### Configuration options\n\nThe `release` class provides several configuration options for customizing the release process. Below are the available\nproperties and if not optional their default values:\n\n```kotlin\nrelease {\n    // Project properties\n    rootGitDirectory.set(layout.projectDirectory.file(\"./\")) // Root directory of the Git repository\n    versionPropertyFile.set(layout.projectDirectory.file(\"version.properties\")) // File containing the version information. Defaults to version.properties, falls back to gradle.properties if not present\n\n    // Check for snapshot / pre-release versions\n    checkForPreReleaseVersions.set(true) // Enable/disable pre-release version checks\n    checkRecursiveForPreReleaseVersions.set(true) // Check submodules for pre-release versions\n    ignorePreReleaseDependenciesFile.set(null) // File listing dependencies to ignore for pre-release checks in form of group:name\n    ignorePreReleaseDependencies.set(emptyList()) // List of dependencies to ignore for pre-release checks in form of group:name\n\n    // Check for uncommitted files\n    checkForUncommittedFiles.set(true) // Enable/disable uncommitted files check\n\n    // Git config\n    gitName.set(null) // If not set, uses the host Git name\n    gitEmail.set(null) //  If not set, uses the host Git email\n    sshKeyFile.set(null) // SSH key file for Git operations, if not set uses the host authentication\n    commitMessagePrefix.set(\"\") // Prefix for commit messages\n    disablePush.set(false) // Disable pushing commits to the remote repository. Useful for local testing\n\n    // Release commit\n    releaseCommitAddFiles.set(listOf(file(\"version.properties\"))) // Files to add in the release commit\n    tagName.set(\"v{version}\") // Tag name format for the release\n    releaseCommitMessage.set(\"Release commit: v{version}\") // Commit message for the release\n\n    // Post release commit\n    postReleaseCommitAddFiles.set(listOf(file(\"version.properties\"))) // Files to add in the post-release commit\n    postReleaseCommitMessage.set(\"Post release commit: v{version}\") // Commit message for the post-release\n    delayBeforePush.set(Duration.ofSeconds(0)) // Delay before pushing the second commit. Some systems aggregate commits that are to close together\n}\n```\n\n### Example with GitHub Actions\n\nYou can use this plugin with any CI/CD system. Here is an example how you can use this plugin with GitHub actions.\n\nThe general workflow will be:\n\n1. Trigger a release with a manual job\n2. For tagged commits, run your release procedure like publishing the artifacts.\n\nTo trigger the release you can take inspiration from the following configuration. This task has two inputs for the\nrelease version and post release version.\n\n\u003cdetails\u003e\n\u003csummary\u003eTrigger Release Action\u003c/summary\u003e\n\n```yaml\n# .github/workflows/trigger-release.yml\nname: Trigger Release\n\non:\n  workflow_dispatch:\n    inputs:\n      release-version:\n        description: 'The version with which the code should be released'\n        type: string\n        required: true\n      post-release-version:\n        description: 'The next snapshot version'\n        type: string\n        required: true\n\n\njobs:\n  trigger-release:\n    runs-on: ubuntu-latest\n    name: Trigger the release\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n        with:\n          # It is important to perform the checkout with an access token. Only with that can the commit trigger a new build!          \n          token: ${{secrets.PERSONAL_ACCESS_TOKEN}}\n\n      # Your setup actions\n\n      # Set the git username and email for the commit\n      # This is optional if you use the gitName \u0026 gitEmail properties from the plugin\n      - name: Set Git User and Email\n        run: |\n          git config --global user.email \"no-reply@github-action.de\"\n          git config --global user.name \"GitHub Action\"\n\n      - name: Run gradle release task\n        run: ./gradlew release -PreleaseVersion=${{ github.event.inputs.release-version }} -PpostReleaseVersion=${{ github.event.inputs.post-release-version }}\n```\n\n\u003c/details\u003e\n\nTo do something with the release add another workflow file that is triggered when a tag is pushed.\n\n\u003cdetails\u003e\n\u003csummary\u003eRelease Tag action\u003c/summary\u003e\n\n```yaml\n# .github/workflows/on-release-tag.yml\n\nname: Release\n\non:\n  push:\n    tags:\n      - v*\n\njobs:\n  release:\n  # Your job configuration\n```\n\n\u003c/details\u003e\n\n### Customizing the release process\n\nYou can easily customize the release process by adding additional tasks and making the\nrelevant tasks depend on your custom tasks. Here are the most interesting tasks performed by the plugin:\n\n1. _writeReleaseVersion_: This task writes the release version to your version file.\n2. _commitReleaseVersion_: This task will create a commit tagged with the release version.\n3. _pushRelease_: This task will perform the push operation.\n4. _writePostReleaseVersion_: This task with write the post release version to your version file.\n5. _commitPostReleaseVersion_: This task will commit the post release version. This commit will not be tagged.\n6. _pushPostRelease_: This task will push the post release version.\n\nPlease note: The plugin will just write the version to the specified version file. Gradle will not automatically reload\nthe version property. The `version` variable from gradle will still show the old version. If you need the\nversion for your custom task, you either have to read the version directly from the file or run multiple gradle\ncommands.\n\n#### Example\n\nLet's assume, you want to write an additional file during the release. You could register your custom task and make the\n_commitReleaseVersion_ task depend on that. If you want to commit this file with the release commit, you can edit the\n_git add_ command in the `release` configuration to include both the version file and your custom file. An example for\nthat is shown below:\n\n```kotlin\n// build.gradle.kts\n\n// Modify the git add command to include your file. You have to specify all files (including the version file). \n// By default, this is just the version file.\nrelease {\n    releaseCommitAddFiles.set(listOf(file(\"version.properties\"), file(\"release-file.txt\")))\n}\n\n// This is your custom task\nval customTask = tasks.register(\"myCustomTask\") {\n    // If you want to do something with the version, depend on the writeReleaseVersion task\n    dependsOn(tasks.writeReleaseVersion)\n    val outputFile = layout.projectDirectory.file(\"release-file.txt\")\n\n    doLast { outputFile.asFile.writeText(\"value\") }\n}\n\n\n// The commit task should depend on your task\ntasks.commitReleaseVersion { dependsOn(customTask) }\n```\n\n## How to contribute\n\nIssues and pull requests are welcome. Please fill out the issue template and provide as much information as possible.\nPlease have a look at the [CONTRIBUTING Guide](CONTRIBUTING.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonhauck%2Fgradle-release-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonhauck%2Fgradle-release-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonhauck%2Fgradle-release-plugin/lists"}