Java Library Development: Get Started Quickly with java-library-template

TLDR: GitHub Template Repository • Gradle Kotlin DSL • GitHub Actions CI/CD Pipeline • One-click Release & Publish to Maven Central • Renovate • Trivy Vulnerability Scan • Issue & PR Templates -> thriving-dev/java-library-template

The 'java-library-template' is a comprehensive solution for Java library developers that simplifies every aspect of library creation and maintenance.

This blog post explores the template's array of features, including one-click project setup, automated releases, security scans, and effortless Javadoc generation. Discover how to keep dependencies up to date with Renovate and ensure seamless publication to Maven Central.

Whether you're a seasoned developer or new to Java, this template empowers you to create high-quality libraries efficiently and with confidence.

Features

• 🥷 One-click automated 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 to Maven Central
• Security & vulnerability scan 🚦 with trivy & GitHub CodeQL Analysis
• Automated dependency updates with Renovate 🤖
• Javadoc deployed with GitHub Pages
• Open Source Community ready (Code of Conduct, Contribution guidelines, Issue & PR Templates)

'java-library-template' in 60s

If you prefer a video over reading this post, there's a 60s intro available on the @thriving_dev YouTube Channel!

Quick Start

Use the template to create your own repository and follow the instructions in the README.md.

CI/CD Pipeline

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

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: Publish SNAPSHOT version to Maven Central and Javadoc (GitHub Pages).
   Runs on pushes to the main branch.
3. Release (Process): Execute (major|minor|patch) release process via Gradle plugin.
   Manually triggered workflow via GitHub UI/API.
4. Release: Publish RELEASE version to Maven Central and Javadoc (GitHub Pages).
   Runs for pushed tags.

Project Structure

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.
• java-library-template/: 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 sub-projects defined.
• gradle.properties: Holds the library version, needed & maintained by the CI/CD pipeline release process.
• **/build.gradle.kts: Gradle build file

Publish to Maven Central

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

• The main branch (per process definition) always is set to the next SNAPSHOT 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 the release process)

Release Process

To release a new version via the CI/CD Pipeline, please follow 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! 🚀

Security & CodeQL Analysis

Common Vulnerabilities and Exposures (CVE)

The libraries gradle dependencies are scanned for known CVE with Trivy. The scan results can be reviewed and managed under 'Security > Vulnerability alerts > Code scanning'.

ℹ️ Trivy is an open-source vulnerability scanner that quickly identifies security vulnerabilities in container images and applications, making it a valuable tool for enhancing the security of containerized environments.

Scans are triggered

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

Please refer to official GitHub documentation for more details.

GitHub CodeQL Analysis

Further, the codebase is analysed with GitHub CodeQL. Please refer to the official docs to learn more about CodeQL.

Javadoc

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.

-> Live preview

Automated Dependency Updates with Renovate

The recommended way to enable renovate is to use the Renovate GitHub App.
This template ships with a prepared renovate.json.

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

Credits

• inspired by https://github.com/cortinico/kotlin-android-template
• PR & issue templates copied / adapted from https://github.com/nuxt/nuxt