Code Monkey home page Code Monkey logo

gitlab4j-api's Introduction

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 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.6.5'
}

Maven: pom.xml

<dependency>
    <groupId>org.gitlab4j</groupId>
    <artifactId>gitlab4j-api</artifactId>
    <version>4.6.5</version>
</dependency>

Javadocs are available here: Javadocs


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("http://your.gitlab.server.com", "YOUR_PRIVATE_TOKEN");

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

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

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 : projectPager.next()) {
        System.out.println(project.getName() + " -: " + project.getDescription());
    }
}
// Create a Pager instance that will be used to build a list containing all the commits for project ID 1234
Pager<Commit> commitPager = gitlabApi.getCommitsApi().getCommits(1234, 20);
List<Commit> allCommits = new ArrayList<>(commitPager.getTotalItems());

// Iterate through the pages and append each page of commits to the list
while (commitPager.hasNext())
    allCommits.addAll(commitPager.next());

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

  CommitsApi
  DeployKeysApi
  EventsApi
  GroupApi
  IssuesApi
  JobApi
  MergeRequestApi
  NamespaceApi
  NotesApi
  PipelineApi
  ProjectApi
  RepositoryApi
  RepositoryFileApi
  ServicesApi
  SessionApi
  UserApi

Sub API Examples

CommitsApi

// 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);

DeployKeysApi

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

EventsApi

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

GroupApi

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

IssuesApi

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

JobApi

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

MergeRequestApi

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

NamespaceApi

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

NotesApi

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

PipelineApi

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

ProjectApi

// Get a list of accessible projects 
public List<Project> projects = gitLabApi.getProjectApi().getProjects();
// Create a new project
Project projectSpec = new Project()
    .withName("my-project")
    .withDescription("My project for demonstration.")
    .withIssuesEnabled(true)
    .withMergeRequestsEnabled(true)
    .withWikiEnabled(true)
    .withSnippetsEnabled(true)
    .withPublic(true);

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

RepositoryApi

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

RepositoryFileApi

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

ServicesApi

// Activates the gitlab-ci service.
getLabApi.getServicesApi().setGitLabCI("project-name", "auth-token", "project-ci-url");

SessionApi

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

UserApi

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

gitlab4j-api's People

Contributors

bobkovalex avatar ccl0326 avatar fgro93 avatar gmessner avatar jlafourc avatar jsimomaa avatar mfriedenhagen avatar orangestas avatar patrikbeno avatar schakko avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.