gitlab4j-api

GitLab4J™ API (gitlab4j-api)

Java Client Library for the GitLab REST API GitLab4J™ API (gitlab4j-api) provides a full featured and easy to consume Java library for working with GitLab repositories via the GitLab REST API. Additionally, full support for working with GitLab webhooks and system hooks is also provided.

GitLab Server Version Support

GitLab4J-API supports both GitLab Community Edition (gitlab-ce) and GitLab Enterprise Edition (gitlab-ee).

NOTICE:
As of GitLab 11.0 support for the GitLab API v3 has been removed from the GitLab server (see https://about.gitlab.com/2018/06/01/api-v3-removal-impending/). Support for GitLab API v3 has been removed from this library in April 2025.

Using GitLab4J-API

Java 11 Requirement

As of GitLab4J-API 6.0.0, Java 11+ is now required to use GitLab4J-API.

Javadocs

Javadocs are available here:

Project Set Up

To utilize GitLab4J™ API in your Java project, simply add the following dependency to your project's build file:

Gradle: build.gradle

dependencies {
    ...
    implementation group: 'org.gitlab4j', name: 'gitlab4j-api', version: '6.3.0'
}

Maven: pom.xml

    org.gitlab4j
    gitlab4j-api
    6.3.0

Jbang:

Jbang is very convinient to run scripts writen in Java having dependencies on third party libraries.

Just add this line at the top of your script:

//DEPS org.gitlab4j:gitlab4j-api:6.3.0

Ivy and SBT

There have been reports of problems resolving some dependencies when using Ivy or SBT, for help resolving those issues see:

JAX-RS API Issue #571

JAX-RS API Issue #572

Lastest version

While we are frequently creating releases, you might be interested by a feature that has not been published yet. You can use jars created by jitpack to get the newest version.

Usage with 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'
    // ...
}

Usage with maven:

  
    jitpack.io
    https://jitpack.io
  

  
    com.github.gitlab4j.gitlab4j-api
    gitlab4j-api
    main-SNAPSHOT
  
  

Usage with jbang:

You just need to declare the dependency like this, instead of using the maven coordinates:

//DEPS https://github.com/gitlab4j/gitlab4j-api/tree/main#gitlab4j-api:SNAPSHOT

Using a specific commit

Version main-SNAPSHOT indicates that you would like to get the latest of the main branch. You can also point to a specific commit:

dependencies {
    implementation 'com.github.gitlab4j.gitlab4j-api:gitlab4j-api:ab6b84c6b0'
}

    com.github.gitlab4j.gitlab4j-api
    gitlab4j-api
    ab6b84c6b0

//DEPS https://github.com/gitlab4j/gitlab4j-api/tree/ab6b84c6b096ea3079d25115a59c272a4ae602aa

Models jar

For some usages, the HTTP layer based on Jersey can't be used. Those projects might want to use the Jackson-based model classes, and implement the REST call themself.

Gradle: build.gradle

dependencies {
    ...
    implementation 'org.gitlab4j:gitlab4j-models:6.3.0'
}

Maven: pom.xml

    org.gitlab4j
    gitlab4j-models
    6.3.0

Usage Examples

GitLab4J-API is quite simple to use, all you need is the URL to your GitLab server and the Personal Access Token from your GitLab Account Settings page. Once you have that info it is as simple as:

// Create a GitLabApi instance to communicate with your GitLab server
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.server.com", "YOUR_PERSONAL_ACCESS_TOKEN");

// Get the list of projects your account has access to
List projects = gitLabApi.getProjectApi().getProjects();

You can also login to your GitLab server with username, and password:

// Log in to the GitLab server using a username and password
GitLabApi gitLabApi = GitLabApi.oauth2Login("http://your.gitlab.server.com", "username", "password");

As of GitLab4J-API 4.6.6, all API requests support performing the API call as if you were another user, provided you are authenticated as an administrator:

// Create a GitLabApi instance to communicate with your GitLab server (must be an administrator)
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.server.com", "YOUR_PERSONAL_ACCESS_TOKEN");

// sudo as as a different user, in this case the user named "johndoe", all future calls will be done as "johndoe"
gitLabApi.sudo("johndoe")

// To turn off sudo mode
gitLabApi.unsudo();

Setting Request Timeouts

As of GitLab4J-API 4.14.21 support has been added for setting the conect and read timeouts for the API client:

GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.com", "YOUR_PERSONAL_ACCESS_TOKEN", proxyConfig);

// Set the connect timeout to 1 second and the read timeout to 5 seconds
gitLabApi.setRequestTimeout(1000, 5000);

Connecting Through a Proxy Server

As of GitLab4J-API 4.8.2 support has been added for connecting to the GitLab server using an HTTP proxy server:

…

See the Javadoc on the GitLabApi class for a complete list of methods accepting the proxy configuration (clientConfiguration parameter)

GitLab API V3 and V4 Support

As of GitLab4J-API 4.2.0 support has been added for GitLab API V4. If your application requires GitLab API V3, you can still use GitLab4J-API by creating your GitLabApi instance as follows:

// Create a GitLabApi instance to communicate with your GitLab server using GitLab API V3
GitLabApi gitLabApi = new GitLabApi(ApiVersion.V3, "http://your.gitlab.server.com", "YOUR_PRIVATE_TOKEN");

NOTICE:
As of GitLab 11.0 support for the GitLab API v3 has been removed from the GitLab server (see https://about.gitlab.com/2018/06/01/api-v3-removal-impending/). Support for GitLab API v3 will be removed from this library sometime in 2019. If you are utilizing the v3 support, please update your code to use GitLab API v4.

Logging of API Requests and Responses

As of GitLab4J-API 4.8.39 support has been added to log the requests to and the responses from the GitLab API. Enable logging using one of the following methods on the GitLabApi instance:

…

Results Paging

GitLab4J-API provides an easy to use paging mechanism to page through lists of results from the GitLab API. Here are a couple of examples on how to use the Pager:

// Get a Pager instance that will page through the projects with 10 projects per page
Pager projectPager = gitLabApi.getProjectApi().getProjects(10);

// Iterate through the pages and print out the name and description
while (projectPager.hasNext()) {
    for (Project project : projectPager.next()) {
        System.out.println(project.getName() + " -: " + project.getDescription());
    }
}

As of GitLab4J-API 4.9.2, you can also fetch all the items as a single list using a Pager instance:

// Get a Pager instance so we can load all the projects into a single list, 10 items at a time:
Pager projectPager = gitlabApi.getProjectsApi().getProjects(10);
List allProjects = projectPager.all();

Java 8 Stream Support

As of GitLab4J-API 4.9.2, all GitLabJ-API methods that return a List result have a similarlly named method that returns a Java 8 Stream. The Stream returning methods use the following naming convention: getXxxxxStream().

IMPORTANT
The built-in methods that return a Stream do so using eager evaluation, meaning all items are pre-fetched from the GitLab server and a Stream is returned which will stream those items. Eager evaluation does NOT support parallel reading of data from ther server, it does however allow for parallel processing of the Stream post data fetch.

To stream using lazy evaluation, use the GitLab4J-API methods that return a Pager instance, and then call the lazyStream() method on the Pager instance to create a lazy evaluation Stream. The Stream utilizes the Pager instance to page through the available items. A lazy Stream does NOT support parallel operations or skipping.

Eager evaluation example usage:

// Stream the visible projects printing out the project name.
Stream projectStream = gitlabApi.getProjectApi().getProjectsStream();
projectStream.map(Project::getName).forEach(name -> System.out.println(name));

// Operate on the stream in parallel, this example sorts User instances by username
// NOTE: Fetching of the users is not done in parallel,
// only the sorting of the users is a parallel operation.
Stream stream = gitlabApi.getUserApi().getUsersStream();
List users = stream.parallel().sorted(comparing(User::getUsername)).collect(toList());

Lazy evaluation example usage:

// Get a Pager instance to that will be used to lazily stream Project instances.
// In this example, 10 Projects per page will be pre-fetched.
Pager projectPager = gitlabApi.getProjectApi().getProjects(10);

// Lazily stream the Projects, printing out each project name, limit the output to 5 project names
projectPager.lazyStream().limit(5).map(Project::getName).forEach(name -> System.out.println(name));

Java 8 Optional Support

GitLab4J-API supports Java 8 Optional<T> for API calls that result in the return of a single item. Here is an example on how to use the Java 8 Optional<T> API calls:

Optional optionalGroup =  gitlabApi.getGroupApi().getOptionalGroup("my-group-path");
if (optionalGroup.isPresent())
    return optionalGroup.get();

return gitlabApi.getGroupApi().addGroup("my-group-name", "my-group-path");

Issue Time Estimates

GitLab issues allow for time tracking. The following time units are currently available:

• months (mo)
• weeks (w)
• days (d)
• hours (h)
• minutes (m)

Conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h.

Making API Calls

The API has been broken up into sub API classes to make it easier to consume and to separate concerns. The GitLab4J sub API classes typically have a one-to-one relationship with the API documentation at GitLab API. Following is a sample of the GitLab4J sub API class mapping to the GitLab API documentation:

org.gitlab4j.api.GroupApi -> https://docs.gitlab.com/ce/api/groups.html

org.gitlab4j.api.MergeRequestApi -> https://docs.gitlab.com/ce/api/merge_requests.html

org.gitlab4j.api.ProjectApi -> https://docs.gitlab.com/ce/api/projects.html

org.gitlab4j.api.UserApi -> https://docs.gitlab.com/ce/api/users.html

Available Sub APIs

The following is a list of the available sub APIs along with a sample use of each API. See the Javadocs for a complete list of available methods for each sub API.

  ApplicationsApi

  ApplicationSettingsApi

  AuditEventApi

  AwardEmojiApi

  BoardsApi

  CommitsApi

  ContainerRegistryApi

  DeployKeysApi

  DiscussionsApi

  EnvironmentsApi

  EpicsApi

  EventsApi

  GroupApi

  HealthCheckApi

  ImportExportApi

  IssuesApi

  JobApi

  [LabelsApi](