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.1.0 No dependencies

Change log GitLab module

Coordinates

groupId

io.github.mcengine

artifactId

github

version

0.1.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.1.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 its methods. Results arrive through a CompletableFuture. An optional fourth constructor argument sets a custom HTTP timeout:

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.1.0").thenAccept(tag -> { /* ... */ });

// Every tag, following pagination past the first 100
platform.getAllTags().thenAccept(tags -> System.out.println(tags.size() + " tags"));

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

// The latest published release and its notes
platform.getLatestRelease().thenAccept(release -> {
    if (release != null) System.out.println(release.getTagName() + ": " + release.getName());
});

// Remaining REST API quota
platform.getRateLimit().thenAccept(rate ->
    System.out.println(rate.getRemaining() + " requests until " + rate.getReset()));

// Optional custom timeout (default is 30 seconds)
GitHubPlatform quick = new GitHubPlatform("MCEngine", "github", token, Duration.ofSeconds(10));

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, releases, and rate-limit status as the read-only GitHubTag, GitHubRelease, and GitHubRateLimit interfaces.

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<List<GitHubTag>> getAllTags()

Resolves to every tag, following the Link header so repositories with more than one page of tags are fully covered.

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.

CompletableFuture<GitHubRelease> getLatestRelease()

Resolves to the latest published release, or null when the repository has no release.

CompletableFuture<GitHubRateLimit> getRateLimit()

Resolves to the current REST API rate-limit status for the token (or the anonymous quota when no token is set).

GitHubTag

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

GitHubRelease

Method	Returns	Description
`getName()`	`String`	Release name (title), or `null` when it has none.
`getTagName()`	`String`	Tag the release was published from, for example `v0.1.0`.
`getBody()`	`String`	Release notes (body), or `null` when empty.

GitHubRateLimit

Method	Returns	Description
`getLimit()`	`int`	Maximum requests permitted in the current window, or `-1` when unknown.
`getRemaining()`	`int`	Requests remaining in the current window, or `-1` when unknown.
`getReset()`	`Instant`	Instant at which the window resets, or `null` when unknown.

A non-success response other than 404 completes the future exceptionally with GitHubApiException, which exposes getStatusCode() and getResponseBody(). A 404 is not an error: lookups resolve to null for a missing resource.

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.