Automated migration completed, enjoy the template.
Use this template to create your own repository
Create & provide a PAT (Personal Access Token) for the CI/CD pipeline
Three workflows commit and push changes to the repository and therefore require additional permissions. ('migrate-repo-template', 'publish-javadoc', 'gradle-release')
The jobs expect a secret by the name CI_GITHUB_TOKEN
that holds a PAT with write permission for Content.
To create a new access token, the following steps are required (ref GitHub documentation):
If the new repo owner is an organisation, enrol the organisation for 'Fine-grained personal access tokens'. In the organisation 'Settings > Third-party Access > Personal access tokens'.
Head to the Developer settings and enrol your personal account for the new 'Fine-grained personal access tokens'. (That's a one-off for your account and you might already have done this before)
Next, click on the button 'Generate new token' and create a token for the target Resource owner, with access to your project and the following 'Repository Permissions'
Provide your new PAT either as an Organisation secret or a Repository secret with the name CI_GITHUB_TOKEN
.
Trigger the '!! INITIAL: Migrate Repo Template !!' workflow
βΉοΈ This workflow automatically 'migrates' all files in your new repository, updating the gradle project group, module name, package names, and all references to the repo <owner>/<name>
.
Final one-off tasks
The project template consists of three top-level folders:
.github/
: Defines the GitHub Actions CI tasks and templates for new pull requests, issues, etc.gradle/
: Contains Gradle Configuration files such as the Gradle Version Catalog and the Gradle Wrapper.utils/
: The library source code (Gradle sub-project).In addition, following files are worth highlighting:
gradle/libs.versions.toml
: A conventional file to declare a version catalog.settings.gradle.kts
: The multi-project Gradle settings file. Here are all the sub-projects defined.gradle.properties
: Holds the library version, needed & maintained by the CI/CD pipeline release process.**/build.gradle.kts
: Gradle build fileThe heart of this template is the 'Main GitHub Actions CI/CD Pipeline'.
The workflow encompasses multiple jobs, modelled and linked with dependencies and conditions. Based on the context (trigger, ref, input arguments) it meets different use cases:
The Maven publish process is fully automated and does not require manual action.
The initial setup for your OSSRH repository requires some manual steps and human review (see why), after which your deployment process is typically modified to get components into OSSRH. These are all one time steps. I recommend to follow the official guide. Check also this
In order to deploy your components to OSSRH with Gradle, you have to meet the requirements for your metadata in the pom.xml as well as supply the required, signed components.
βΉοΈ The publish process uses io.github.gradle-nexus.publish-plugin under the hood.
The gradle project as well as the CI/CD pipeline is already fully prepared for the publishing process. The GH actions job callable.publish-sonatype.yml requires the following Secrets:
Secret name | Value |
---|---|
OSSRH_USERNAME |
The username of your OSSRH account. |
OSSRH_PASSWORD |
The password of your OSSRH account. |
GPG_SIGNING_KEY |
The GPG private key to sign your artifacts (in ascii-armored format). You can obtain it with gpg --armor --export-secret-keys <your@email.here> or you can create one key online on pgpkeygen.com. |
GPG_SIGNING_PASSPHRASE |
The passphrase for unlocking the secret key. (you picked it when creating the key). |
Please define the secrets via your repository settings. (Settings > Security > Secrets and variables > Actions)
To release a new version via the CI/CD Pipeline, please follow the instructions below.
The release process includes
The new version is automatically published to Maven Central! π
CI_GITHUB_TOKEN
The CI/CD 'gradle-release' job expects a secret by the name CI_GITHUB_TOKEN
that holds a PAT (Personal Access Token) with permission to push tags as part of the release process.
If you have been following the Quick Start guide you should already have this configured. Please refer to 'Quick Start' step 2.
A Javadoc website of your library, generated by gradle, is 'published' to GitHub Pages by the CI/CD pipeline. In addition to each released version, the current snapshot version (main branch) is published as current
.
-> visit the live preview.
To host the generated Javadoc, configure GitHub Pages for your repository to deploy from branch gh-pages
. You can also find all deployments under 'pages-build-deployment'.
βΉοΈ The branch is created with the first CI/CD pipeline run. ('Publish javadoc' job)
The libraries gradle dependencies are scanned for known CVE with aquasecurity/trivy. The scan results can be reviewed and managed under Security > Vulnerability alerts > Code scanning.
Scans are triggered
Please refer to official GitHub documentation for more details.
This template ships with a prepared renovate.json.
The recommended way to enable renovate is to use the Renovate GitHub App.