Repository files navigation

TLDR: Java Library GitHub Template Repository

• Introducing 'java-library-template' in 60s - YouTube
• https://thriving.dev/blog/java-library-development-get-started-quickly-with-java-library-template

• 🥷 One-clickautomated initial project migration workflow (GitHub Action)
• Java 21 (corretto) 🤝Gradle Kotlin DSL, version catalog
• GitHub Actions CI/CD pipeline, 👷 efficient build pipeline, caching, integration tests, test report & failed test annotations
• 🚀One-click release process +publish toMaven Central
• Security & 🚦 Vulnerability scan withtrivy & GitHub CodeQL Analysis
• Automated dependency updates withRenovate 🤖
• Javadoc deployed withGitHub Pages
• Open SourceCommunity ready (Code of Conduct, Contribution guidelines, Issue & PR Templates)

Demo on YouTube: java-library-template 1/7: Getting started (generate from; create PAT, one-click migrate)

1. Use this template to create your own repository

2. 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 nameCI_GITHUB_TOKEN that holds a PAT withwrite permission forContent.

   To create a new access token, the following steps are required (refGitHub documentation):

   1. 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'.

   2. Head to theDeveloper settings andenrol 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)

   3. Next, click on the button 'Generate new token' and create a token for the targetResource owner, with access to your project and the following 'Repository Permissions'

      • Contents:Read andWrite access to code
      • Metadata:Read access to metadata
      

   4. Provide your new PAT either as an Organisation secret or a Repository secret with the nameCI_GITHUB_TOKEN.

      

3. Trigger the '!! INITIAL: Migrate Repo Template !!' workflow

   ℹ️ This workflow automatically 'migrates' all files in your new repository, updating thegradle project group,module name,package names, andall references to the repo<owner>/<name>.

   • Head over toActions (1)
   • on the left-hand side select the topmost workflow '!! INITIAL: Migrate Repo Template !!' (2)
   • click theRun workflow button (3)
   • fill out the form &start the pipeline (4)(5)

   

4. Final one-off tasks

   • Choose & update the LICENSE,here
   • UpdateMaven Publication detailshere
   • Configure GitHub Pages to deploy branch 'gh-pages' (Javadoc)
   • Add secrets required forpublishing to Maven Central
   • Install & configure renovate app (instructions)

The project template consists of three top-levelfolders:

• .github/: Defines the GitHub Actions CI tasks and templates for new pull requests, issues, etc.
• gradle/: Contains Gradle Configuration files such as the GradleVersion Catalog and the Gradle Wrapper.
• java-library-template/: The library source code (Gradle sub-project).

In addition, followingfiles are worth highlighting:

• gradle/libs.versions.toml: Aconventional 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 pipelinerelease process.
• **/build.gradle.kts: Gradle build file

The heart of this template is the 'Main GitHub Actions CI/CD Pipeline'. See it inActions (👻).

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:

1. Check. Build, test, integration test; code quality & vulnerability scans.
   Runs for active PRs - as well as part of all subsequent listed use cases.
2. Latest. 'Check', publish SNAPSHOT version to Maven Central and Javadoc (GitHub Pages).
   Runs on pushes to the main branch.
3. Release Process. 'Check', executes (major|minor|patch) release process via the Gradle plugin.
   Manually triggered workflow via GitHub UI/API.
4. Library Release. 'Check', publish RELEASE version to Maven Central and Javadoc (GitHub Pages).
   Runs for pushed tags.

The Maven publish process is fully automated and does not require manual action.

• Themain branch (per process definition) always is set to the nextSNAPSHOT version and is published to the Sonatype snapshot repository with each main CI/CD pipeline run. The pipeline runs e.g. when a PR is merged, but can also be triggered manually.
• Release deployment happens when a new tag is pushed to GitHub. (Part of therelease process)

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 theofficial guide.

In order to deploy your components to OSSRH with Gradle, you have to meet therequirements for your metadata in the pom.xml as well as supply the required, signed components.

ℹ️ The publish process usesio.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 jobcallable.publish-sonatype.yml requires the following Secrets:

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.

• Navigate to Actions (1)
• > Main Pipeline (2)
• Click 'Run workflow' button (3)
• Select a semver release type with the 'Release Library' dropdown (4)
• 'Run the workflow' (5)

The release process includes

• Pipeline run (incl. build & tests) that executes the release plugin (6)
• The release plugin first sets & commits the new version (7a)
• Creates & pushes a new tag (7b)
• Sets the main branch to the next SNAPSHOT version (7c)

The new version is automatically published to Maven Central! 🚀

The CI/CD 'gradle-release' job expects a secret by the nameCI_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 ascurrent.
-> visit thelive preview.

To host the generated Javadoc, configure GitHub Pages for your repository to deploy from branchgh-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 knownCVE withaquasecurity/trivy. The scan results can be reviewed and managed under 'Security > Vulnerability alerts > Code scanning'.

Scans are triggered

1. with each main CI/CD pipeline run
2. Scheduled (weekly) (ref)

Please refer toofficial GitHub documentation for more details.

ℹ️ Renovate (RenovateBot) is a software tool that automates the process of keeping software dependencies up-to-date by scanning code repositories, identifying outdated dependencies, and generating automated pull requests to update them.

It’s Open Source and Community-Driven, supports a wide range of programming languages and package managers, and integrates with GitHub & Gitlab as well as other popular CI/CD systems.

This template ships with a preparedrenovate.json.

The recommended way to enable renovate is to use theRenovate GitHub App.

• inspired byhttps://github.com/cortinico/kotlin-android-template
• PR & issue templates copied / adapted fromhttps://github.com/nuxt/nuxt

java-library-template bythriving.dev is licensed underCC BY-NC-SA 4.0