Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Gitlab API on the plugin site for more information.

This plugin is a library plugin used by other GitHub related plugins to share the same libraries. This plugin does not have any user visible feature by itself. There's no need to install this plugin manually, although you want to keep it up to date for new features and bug fixes.

GitLab API Plugin

This plugin wraps GitLab Java Api by gmessner

Reasons for developing GitLab Api Plugin:

This plugin was developed as a part of Google Summer of Code (GSoC) 2019 project under Multibranch Pipeline Support for GitLab. Inspired from GitHub API Plugin.

The GitLab Plugin defines a set of GitLab APIs which performs build triggers and authentication and some branch source functionality. The API defined inside doesn't fully support al GitLab APIs which limits the future scope of expansion of the GitLab Plugin. One of the missing feature in the API is detecting Merge Requests which is the reason GitLab Branch Source Functionality for Multibranch Pipeline is not supported in the GitLab Plugin.

Note: In Jenkins SCM Plugins, PRs/MRs are detected as new branches.

GitLab Branch Source Plugin, not released at the time of this plugin creation, can also use this API plugin to implement missing branch source functionality for GitLab and at the same time follow the 3 plugins conventions of other SCM (GitHub) Plugins, namely:

1) <SCM>-api-plugin: For wrapping <scm> API into a plugin

2) <SCM>-plugin: For build triggers, auth and webhooks management

3) <SCM>-branch-source-plugin: For branches, MRs, tags indexing and build for all jobs (Freestyle, Pipeline, Multibranch Pipeline, Folder Organisation)

Reason for wrapping the GitLab4J Api into a plugin:

The main advantage to using an API plugin is to allow the library to be reused by other plugins without each plugin needing to maintain updates to the dependencies manually. Instead, the API plugin is used for those libraries which reduces maintenance burden, especially whenever CVEs are discovered. (by Unknown User (jvz) )

For technical details see this: https://jenkins.io/doc/developer/plugin-development/dependencies-and-class-loading/#using-library-wrapper-plugins (by Unknown User (jglick))

Reasons for choosing gitlab4j over other GitLab Java APIs: 

Contributed by GitLab4J API author

What was motivation behind development of gitlab4j when java-gitlab-api existed?

One thing to keep in mind is that there is a mis-perception that java-gitlab-api is the “official” Java library for the GitLab API because it uses the org.gitlab package name.  However it is not the “official” Java library, nor is there an “official” Java library for the GitLab API. The author of this library is incorrectly using the org.gitlab package name, normally the package name is the reversed domain name for the developer of the package.  

java-gitlab-api (May 20, 2013) is not much older than gitlab4j (Feb 18, 2014).  I evaluated java-gitlab-api before deciding to develop gitlab4j. What I determined is that it was not well designed and had poor code coverage. The main class for using java-gitlab-api, org.gitlab.api.GitlabAPI is > 4000 lines of code and every single endpoint call goes through this single class.  java-gitlab-api also had no support for Webhooks at the time, which was one of my primary needs.

gitlab4j is quite different, it separates the API into the same sub APIs that the GitLab API documentation does.  I believe this makes it much easier for devs to consume and understand. Here is a sampling of the gitlab4j 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

In addition, every single model class in gitlab4j is tested for correct JSON based on both the GitLab API documentation and the actual JSON from the GitLab API services.  Additionally, there is a significant number of integration tests being done. gitlab4j also has significant built-in support for the GitLab webhooks and system hooks.

Is there any issues/missing features in java-gitlab-api that gitlab4j-api solves?

The java-gitlab-api is missing many of the GitLab APIs and in many of the implemented APIs, java-gitlab-api is missing many methods.  While gitlab4j-api does not have 100% coverage of the GitLab API, it is pretty close, and if you read thru the issues and pull requests for gitlab4j-api, you will see that support for un-implemented GitLab APIs is quickly added when someone asks for it.  This is why there is a significant number of releases for gitlab4j-api, where java-gitlab-api rarely releases. GitLab releases new features quite often and gitlab4j-api tries as best as possible to keep up with those new releases, both in new features and other changes that are introduced.  I would estimate that gitlab4j-api has implemented at minimum, at least twice as many of the GitLab APIs as java-gitlab-api has.

gitlab4j-api also has complete support for Java 8 Streams and Optional, which is completly missing from java-gitlab-api.

Is gitlab4j missing something or having issues?

GitLab is continuously evolving and adding new APIs and additional methods to existing APIs, it is quite difficult to keep up with this.  What I have done is implement new features both when they are asked for and also when I see an interesting new feature in a new GitLab release.   I strive to cover as much of the GitLab APIs as possible, this will be a never ending commitment.

At this time,  gitlab4j-api has no known issues, but it is software, and I’m sure there are bugs in it somewhere, but any and all problems are quickly addressed when they are discovered.

Is there any immediate future plans for improvements?

The only thing currently in the roadmap and actively being worked on is the addition of fabric8.io docker support for doing the integration tests.  I am doing this so that future releases of gitlab4j-api will be fully automated using Jenkins.

There is also an issue concerning the use of Java 8+ Temporals for date/time fields (https://github.com/gmessner/gitlab4j-api/issues/261).  I was planning on doing that this year, but am actually reconsidering, as it will cause a lot of work for existing consumers of gitlab4j-api to make the necessary code changes that this breaking change will require.  This change has only been requested by 1 user and 2 other users that liked the request. Considering that there are over 6000 downloads of gitlab4j-api per month, this change might be a very bad idea.

Issues solved:

Used maven enforcer plugin to ignore javax library which targetted to Java 9 while maven java level was set to Java 8. See this thread for more info.


Key Summary T Created Updated Due Assignee Reporter P Status Resolution
Loading...
Refresh