View Gitlab API on the plugin site for more information.
GitLab API Plugin
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 Matt Sicker )
For technical details see this: https://jenkins.io/doc/developer/plugin-development/dependencies-and-class-loading/#using-library-wrapper-plugins (by Jesse Glick)
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.
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.