Module

gitlab

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

Java 21 v0.1.0 No dependencies

Change log GitHub module

Coordinates

groupId

io.github.mcengine

artifactId

gitlab

version

0.1.0

namespace

io.github.mcengine.gitlab

class

io.github.mcengine.gitlab.common.GitLabPlatform

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/gitlab")
        credentials {
            username = System.getenv("GITHUB_ACTOR")
            password = System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation "io.github.mcengine:gitlab:0.1.0"
}

GITHUB_ACTOR and GITHUB_TOKEN authenticate against GitHub Packages, where the artifact is hosted. At runtime the library talks to the GitLab API; supply a GitLab token in code only for private projects.

Usage

Construct the platform with an owner and project, then call any of its methods. Results arrive through a CompletableFuture. An optional fourth constructor argument sets a custom HTTP timeout:

Example

GitLabPlatform platform = new GitLabPlatform("MCEngine", "gitlab");

// Latest tag (or null when the project 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 (read from the RateLimit-* headers)
platform.getRateLimit().thenAccept(rate ->
    System.out.println(rate.getRemaining() + " requests until " + rate.getReset()));

// For a private project, pass a GitLab token (sent as the PRIVATE-TOKEN header):
GitLabPlatform authed = new GitLabPlatform("MCEngine", "gitlab", gitlabToken);

// Optional custom timeout (default is 30 seconds)
GitLabPlatform quick = new GitLabPlatform("MCEngine", "gitlab", gitlabToken, 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 GitLabPlatform. It returns tags, releases, and rate-limit status as the read-only GitLabTag, GitLabRelease, and GitLabRateLimit interfaces.

CompletableFuture<GitLabTag> getLatestTag()

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

CompletableFuture<GitLabTag> getTag(String tagName)

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

CompletableFuture<List<GitLabTag>> getAllTags()

Resolves to every tag, following the Link header so projects 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 project has no tags.

CompletableFuture<GitLabRelease> getLatestRelease()

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

CompletableFuture<GitLabRateLimit> getRateLimit()

Resolves to the current REST API rate-limit status, read from the RateLimit-* response headers.

GitLabTag

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

GitLabRelease

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 (the release description), or `null` when empty.

GitLabRateLimit

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

A non-success response other than 404 completes the future exceptionally with GitLabApiException, 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.

How is the GitLab project addressed?

By its URL-encoded owner/project path, so you pass the owner and project name and the library builds the request for you.

Does it cache results?

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