Module

github

A dependency-free Java library that reads tag and version information from the GitHub REST API through a single source-of-truth class, GitHubPlatform. Every call is asynchronous and returns a CompletableFuture.

Java 21 v0.0.0 No dependencies

Change log GitLab module

Coordinates

groupId

io.github.mcengine

artifactId

github

version

0.0.0

namespace

io.github.mcengine.github

class

io.github.mcengine.github.common.GitHubPlatform

Add the dependency

The library is published to its own GitHub Packages registry. Authenticate with a token that has the read:packages scope, then declare the dependency (Gradle, Groovy DSL):

build.gradle

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/MCEngine/github")
        credentials {
            username = System.getenv("GITHUB_ACTOR")
            password = System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation "io.github.mcengine:github:0.0.0"
}

GITHUB_ACTOR is your GitHub username and GITHUB_TOKEN is a token with package read access. Reading tags from a public repository needs no token at runtime.

Usage

Construct the platform with an owner and repository, then call any of the three methods. Results arrive through a CompletableFuture:

Example

GitHubPlatform platform = new GitHubPlatform("MCEngine", "github");

// Latest tag (or null when the repository has no tags)
platform.getLatestTag().thenAccept(tag -> {
    System.out.println(tag == null ? "no tags yet" : tag.getName());
});

// A specific tag by name (or null when it does not exist)
platform.getTag("v0.0.0").thenAccept(tag -> { /* ... */ });

// Is the latest tag newer than a plain version? (the "v" prefix is handled)
boolean newer = platform.CompareVersion("0.0.0").join();

Pass the version to CompareVersion without a prefix (for example 1.0.0). Tags stored as v1.0.0 have the v removed before the Major.Minor.Patch comparison.

Method reference

Import only GitHubPlatform. It returns tags as the read-only GitHubTag interface.

CompletableFuture<GitHubTag> getLatestTag()

Resolves to the latest tag by semantic version, or null when the repository has no tags.

CompletableFuture<GitHubTag> getTag(String tagName)

Resolves to the tag whose name equals tagName, or null when it does not exist.

CompletableFuture<Boolean> CompareVersion(String version)

Resolves to true when the latest tag is a newer semantic version than version; false when it is not newer or when the repository has no tags.

GitHubTag

Method	Returns	Description
`getName()`	`String`	Tag name as stored on GitHub, for example `v0.0.0`.
`getCommitSha()`	`String`	Commit SHA the tag points at, or `null` when unknown.

FAQ

Does it pull in any third-party libraries?

No. The module uses only the Java Platform — the built-in HTTP client and CompletableFuture — so it adds no transitive dependencies.

Why does every method return a CompletableFuture?

Each call waits for data from the GitHub REST API. Returning a future keeps the call non-blocking so you can compose it with the rest of your asynchronous code.

Does it cache results?

No. The class holds only the connection details you pass in; every call fetches fresh data and returns it.