repository·main·Indexed 22 days ago
https://github.com/gitlab4j/gitlab4j-apiA full-featured Java client library for the GitLab REST API (v4) compatible with GitLab Community and Enterprise Editions. It enables programmatic interaction with repositories, webhooks, and system hooks. The library requires Java 11+ as of version 6.0.0 and provides specialized sub-APIs for managing projects, issues, merge requests, pipelines, and more. It includes support for various authentication methods, proxy configuration, and flexible data retrieval strategies using Pagers and Streams.
The GitLab4J-API is organized into specialized sub-API classes to separate concerns and make consumption easier. Each sub-API class typically has a one-to-one relationship with the corresponding section of the official GitLab REST API documentation.
To make an API call, you access the relevant sub-API through the main gitLabApi instance using getter methods (e.g., gitLabApi.getProjectApi()).
// Example mapping
// org.gitlab4j.api.ProjectApi -> https://docs.gitlab.com/ce/api/projects.html
// Accessing the sub-API
ProjectApi projectApi = gitLabApi.getProjectApi();GitLab4J-API is compatible with both:
Important Note on API Versions: Support for GitLab API v3 was removed from this library in April 2025, following its removal from the GitLab server starting with GitLab 11.0. This library focuses on GitLab API v4.
When dealing with lists of items (like projects or users), you have three main strategies:
Pager<T> to iterate through pages. This is memory-efficient and allows for lazy evaluation via .lazyStream(). A lazy stream does NOT support parallel operations or skipping.pager.all() to fetch all items into a single list immediately.Stream() (e.g., getProjectsStream()). These perform eager evaluation, meaning all items are pre-fetched from the server before the stream is returned. This allows for parallel processing (e.g., .parallel()) but is not memory-efficient for massive datasets.Summary Table:
| Method | Evaluation | Parallelism | Best For |
|---|---|---|---|
Pager.next() | Lazy | No | Memory efficiency |
Pager.all() | Eager | N/A | Small/Medium lists |
get...Stream() | Eager | Yes (post-fetch) | Parallel processing |
Pager.lazyStream() | Lazy | No | Large datasets |
// 1. Manual Paging
Pager<Project> projectPager = gitLabApi.getProjectApi().getProjects(10);
while (projectPager.hasNext()) {
for (Project project : projectPager.next()) {
System.out.println(project.getName());
}
}
// 2. Eager List from Pager
List<Project> allProjects = gitLabApi.getProjectsApi().getProjects(10).all();
// 3. Eager Stream (supports parallel processing)
Stream<Project> projectStream = gitLabApi.getProjectApi().getProjectsStream();
projectStream.parallel().forEach(p -> System.out.println(p.getName()));
// 4. Lazy Stream (via Pager)
Pager<Project> lazyPager = gitLabApi.getProjectApi().getProjects(10);
lazyPager.lazyStream().limit(5).forEach(p -> System.out.println(p.getName()));If you need features not yet in a formal release, you can use JitPack to pull the latest main branch or specific commits.
Gradle:
Add the JitPack repository and use the main-SNAPSHOT version.
Maven:
Add the JitPack repository and use the main-SNAPSHOT version.
Jbang: Use the direct GitHub tree URL with the specific branch or commit.
### Usage with gradle:
```gradle
repositories {
mavenCentral()
maven {
url "https://jitpack.io"
content {
includeGroup "com.github.gitlab4j.gitlab4j-api"
}
}
}
dependencies {
implementation 'com.github.gitlab4j.gitlab4j-api:gitlab4j-api:main-SNAPSHOT'
}<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.gitlab4j.gitlab4j-api</groupId>
<artifactId>gitlab4j-api</artifactId>
<version>main-SNAPSHOT</version>
</dependency>
</dependencies>//DEPS https://github.com/gitlab4j/gitlab4j-api/tree/main#gitlab4j-api:SNAPSHOTdependencies {
implementation 'com.github.gitlab4j.gitlab4j-api:gitlab4j-api:ab6b84c6b0'
}If your project cannot use the HTTP layer based on Jersey, you can use the Jackson-based model classes independently by adding the gitlab4j-models dependency. This allows you to implement the REST calls yourself while reusing the library's data models.
### Gradle: build.gradle
```java
dependencies {
implementation 'org.gitlab4j:gitlab4j-models:6.3.0'
}<dependency>
<groupId>org.gitlab4j</groupId>
<artifactId>gitlab4j-models</artifactId>
<version>6.3.0</version>
</dependency>To use GitLab4J-API in your Java project, add the dependency to your build configuration. Note that as of version 6.0.0, Java 11+ is required.
### Gradle: build.gradle
```java
dependencies {
implementation group: 'org.gitlab4j', name: 'gitlab4j-api', version: '6.3.0'
}<dependency>
<groupId>org.gitlab4j</groupId>
<artifactId>gitlab4j-api</artifactId>
<version>6.3.0</version>
</dependency>Add this line to the top of your script:
//DEPS org.gitlab4j:gitlab4j-api:6.3.0Use WikisApi to list pages within a project's wiki.
// Get a list of pages in project wiki
List<WikiPage> wikiPages = gitLabApi.getWikisApi().getPages();Use HealthCheckApi to check the liveness of the GitLab server. Note: This may require IP whitelisting on the GitLab server.
// Get the liveness endpoint health check results.
HealthCheckInfo healthCheck = gitLabApi.getHealthCheckApi().getLiveness();Use ApplicationsApi to manage OAuth applications on the GitLab server.
// Add an OAUTH Application to GitLab
ApplicationScope[] scopes = {ApplicationScope.SUDO, ApplicationScope.PROFILE};
gitLabApi.getApplicationsApi().createApplication("My OAUTH Application", "https//example.com/myapp/callback", scopes);Use AwardEmojiApi to interact with emojis on issues or other entities.
// Get a list of AwardEmoji belonging to the specified issue (group ID = 1, issues IID = 1)
List<AwardEmoji> awardEmojis = gitLabApi.getAwardEmojiApi().getIssuAwardEmojis(1, 1);Use AuditEventApi to retrieve audit events. This API utilizes the org.gitlab4j.api.utils.ISO8601 utility class for date handling.
// Get the current GitLab server audit events for entity
Date since = ISO8601.toDate("2017-01-01T00:00:00Z");
Date until = new Date(); // now
List<AuditEvent> auditEvents = gitLabApi.getAuditEventApi().getAuditEvents(since, until, EntityType.USER, 1);