GitLab API for Java (gitlab4j-api) provides a full featured Java API for working with GitLab repositories via the GitLab REST API
Switch branches/tags
gitlab4j-api-4.8.32 gitlab4j-api-4.8.31 gitlab4j-api-4.8.30 gitlab4j-api-4.8.29 gitlab4j-api-4.8.28 gitlab4j-api-4.8.27 gitlab4j-api-4.8.26 gitlab4j-api-4.8.25 gitlab4j-api-4.8.24 gitlab4j-api-4.8.23 gitlab4j-api-4.8.22 gitlab4j-api-4.8.21 gitlab4j-api-4.8.20 gitlab4j-api-4.8.19 gitlab4j-api-4.8.18 gitlab4j-api-4.8.17 gitlab4j-api-4.8.16 gitlab4j-api-4.8.15 gitlab4j-api-4.8.14 gitlab4j-api-4.8.12 gitlab4j-api-4.8.11 gitlab4j-api-4.8.10 gitlab4j-api-4.8.9 gitlab4j-api-4.8.8 gitlab4j-api-4.8.7 gitlab4j-api-4.8.6 gitlab4j-api-4.8.5 gitlab4j-api-4.8.4 gitlab4j-api-4.8.3 gitlab4j-api-4.8.2 gitlab4j-api-4.8.1 gitlab4j-api-4.8.0 gitlab4j-api-4.7.17 gitlab4j-api-4.7.16 gitlab4j-api-4.7.15 gitlab4j-api-4.7.14 gitlab4j-api-4.7.12 gitlab4j-api-4.7.11 gitlab4j-api-4.7.10 gitlab4j-api-4.7.9 gitlab4j-api-4.7.8 gitlab4j-api-4.7.7 gitlab4j-api-4.7.6 gitlab4j-api-4.7.5 gitlab4j-api-4.7.4 gitlab4j-api-4.7.3 gitlab4j-api-4.7.2 gitlab4j-api-4.7.1 gitlab4j-api-4.7.0 gitlab4j-api-4.6.9 gitlab4j-api-4.6.8 gitlab4j-api-4.6.6 gitlab4j-api-4.6.5 gitlab4j-api-4.6.4 gitlab4j-api-4.6.3 gitlab4j-api-4.6.2 gitlab4j-api-4.6.1 gitlab4j-api-4.6.0 gitlab4j-api-4.5.0 gitlab4j-api-4.4.8 gitlab4j-api-4.4.7 gitlab4j-api-4.4.6 gitlab4j-api-4.4.5 gitlab4j-api-4.4.4 gitlab4j-api-4.4.3 gitlab4j-api-4.4.2 gitlab4j-api-4.4.1 gitlab4j-api-4.4.0 gitlab4j-api-4.3.6 gitlab4j-api-4.3.5 gitlab4j-api-4.3.4 gitlab4j-api-4.3.3 gitlab4j-api-4.3.2 gitlab4j-api-4.3.1 gitlab4j-api-4.3.0 gitlab4j-api-4.2.5 gitlab4j-api-4.2.4 gitlab4j-api-4.2.3 gitlab4j-api-4.2.2 gitlab4j-api-4.2.1 gitlab4j-api-4.2.0 gitlab4j-api-4.1.6 gitlab4j-api-4.1.5 gitlab4j-api-4.1.4 gitlab4j-api-4.1.3 gitlab4j-api-4.1.2 gitlab4j-api-4.1.1 gitlab4j-api-4.1.0 gitlab4j-api-4.0.9 gitlab4j-api-4.0.8 gitlab4j-api-4.0.7 gitlab4j-api-4.0.6 gitlab4j-api-4.0.5 gitlab-api-4.0.4 gitlab-api-4.0.3 gitlab-api-4.0.2 gitlab-api-4.0.1 gitlab-api-4.0.0 gitlab-api-3.0.1 gitlab-api-3.0.0
Nothing to show
Clone or download

GitlLab API for Java (gitlab4j-api)

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

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

Gradle: build.gradle

dependencies {
    compile group: 'org.gitlab4j', name: 'gitlab4j-api', version: '4.8.32'

Maven: pom.xml


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


Javadocs are available here: Javadocs

Java 8 Requirement

As of GitLab4J-API 4.8.0, Java 8+ is now required to use GitLab4J-API.

Using GitLab4J

GitLab4J-API is quite simple to use, all you need is the URL to your GitLab server and the Private 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("", "YOUR_PRIVATE_TOKEN");

// Get the list of projects your account has access to
List<Project> 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.login("", "your-username", "your-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("", "YOUR_PRIVATE_TOKEN");

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

// To turn off sudo mode

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:

// Log in to the GitLab server using a proxy server (with basic auth on proxy)
Map<String, Object> proxyConfig = ProxyClientConfig.createProxyClientConfig(
        "http://your-proxy-server", "proxy-username", "proxy-password");
GitLabApi gitLabApi = new GitLabApi("", "YOUR_PRIVATE_TOKEN", null, proxyConfig);

// Log in to the GitLab server using a proxy server (no auth on proxy)
Map<String, Object> proxyConfig = ProxyClientConfig.createProxyClientConfig("http://your-proxy-server");
GitLabApi gitLabApi = new GitLabApi("", "YOUR_PRIVATE_TOKEN", null, proxyConfig);

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, "", "YOUR_PRIVATE_TOKEN");

As of GitLab 11.0 support for the GitLab API v3 has been removed (see Support for GitLab API v3 will be removed from this library in January 2019. If you are utilizing the v3 support, please update your code before January 2019.

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<Project> projectPager = gitlabApi.getProjectsApi().getProjects(10);

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

Java 8 Optional<T> 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<Group> optionalGroup =  gitlabApi.getGroupApi().getGroup("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 APIs classes to make it easier to learn and to separate concerns. Following is a list of the sub APIs along with a sample use of each API. See the Javadocs for a complete list of available methods for each sub API.

Available Sub APIs


Sub API Examples


// Get a list of AwardEmoji belonging to the specified issue (group ID = 1, issues IID = 1)
List<AwardEmoji> awardEmojis = gitLabApi.getAwardEmojiApi().getIssuAwardEmojis(1, 1);


// Get a list of commits associated with the specified branch that fall within the specified time window
// This uses the ISO8601 date utilities the in org.gitlab4j.api.utils.ISO8601 class
Date since = ISO8601.toDate("2017-01-01T00:00:00Z");
Date until = new Date(); // now
List<Commit> commits = gitLabApi.getCommitsApi().getCommits(1234, "new-feature", since, until);


// Get a list of DeployKeys for the authenticated user
List<DeployKey> deployKeys = gitLabApi.getDeployKeysApi().getDeployKeys();


// Get a list epics of the requested group and its subgroups.
List<Epic> epics = gitLabApi.getEpicsApi().getEpics(1);


// Get a list of Events for the authenticated user
Date after = new Date(0); // After Epoch
Date before = new Date(); // Before now
List<Event> events = gitLabApi.getEventsApi().getAuthenticatedUserEvents(null, null, before, after, DESC);


// Get a list of groups that you have access to
List<Group> groups = gitLabApi.getGroupApi().getGroups();


// Get the liveness endpoint health check results. Assumes ip_whitelisted per:
HealthCheckInfo healthCheck = gitLabApi.getHealthCheckApi().getLiveness();


// Get a list of issues for the specified project ID
List<Issue> issues = gitLabApi.getIssuesApi().getIssues(1234);


// Get a list of jobs for the specified project ID
List<Job> jobs = gitLabApi.getJobApi().getJobs(1234);


// Get a list of labels for the specified project ID
List<Label> labels = gitLabApi.getLabelsApi().getLabels(1234);


// Get a list of the merge requests for the specified project
List<MergeRequest> mergeRequests = gitLabApi.getMergeRequestApi().getMergeRequests(1234);


// Get a list of the milestones for the specified project
List<Milestone> milestones = gitLabApi.getMilestonesApi().getMilestones(1234);


// Get all namespaces that match "foobar" in their name or path
List<Namespace> namespaces = gitLabApi.getNamespaceApi().findNamespaces("foobar");


// Get a list of the issues's notes for project ID 1234, issue IID 1
List<Note> notes = gitLabApi.getNotesApi().getNotes(1234, 1);


// Get the current global notification settings
NotificationSettings settings = gitLabApi.getNotificationSettingsApi().getGlobalNotificationSettings();


// Get all pipelines for the specified project ID
List<Pipeline> pipelines = gitLabApi.getPipelineApi().getPipelines(1234);


// Get a list of accessible projects 
public List<Project> projects = gitLabApi.getProjectApi().getProjects();
// Create a new project
Project projectSpec = new Project()
    .withDescription("My project for demonstration.")

Project newProject = gitLabApi.getProjectApi().createProject(projectSpec);


List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());


// Get a list of repository branches from a project, sorted by name alphabetically
List<Branch> branches = gitLabApi.getRepositoryApi().getBranches();


// Get info (name, size, ...) and the content from a file in repository
RepositoryFile file = gitLabApi.getRepositoryFileApi().getFile("file-path", 1234, "ref");   


// Get All Runners.
List<Runner> runners = gitLabApi.getRunnersApi().getAllRunners();


// Activate/Update the Slack Notifications service
SlackService slackService =  new SlackService()
gitLabApi.getServicesApi().updateSlackService("project-path", slackService);


// Log in to the GitLab server and get the session info
gitLabApi.getSessionApi().login("your-username", "your-email", "your-password");


// Get a list of the authenticated user's snippets
List<Snippet> snippets = gitLabApi.getSnippetsApi().getSnippets();


// Get a list of installed system hooks
List<SystemHook> hooks = gitLabApi.getSystemHooksApi().getSystemHooks();


// Get the User info for user_id 1
User user = gitLabApi.getUserApi().getUser(1);

// Create a new user with no password who will recieve a reset password email
User userConfig = new User()
    .withName("Jane Doe")
String password = null;
boolean sendResetPasswordEmail = true;
gitLabApi.getUserApi().createUser(userConfig, password, sendResetPasswordEmail);