<SOURCE_TEXT>

GitLab4J™ API (gitlab4j-api)
GitLab REST API的Java客户端库

GitLab4J™ API (gitlab4j-api) 提供了一个功能齐全且易于使用的Java库,用于通过GitLab REST API操作GitLab仓库。此外,还提供了对GitLab webhooks和系统钩子的全面支持。

目录

• GitLab服务器版本支持
  
• 使用GitLab4J-API
  
  • Java 8要求
    
  • Javadocs
    
  • 项目设置
    
  • 使用示例
    
  • 设置请求超时
    
  • 通过代理服务器连接
    
  • 支持GitLab API V3和V4
    
  • API请求和响应的日志记录
    
  • 结果分页
    
  • Java 8流支持
    
    • 即时评估用法示例
      
    • 延迟评估用法示例
      
  • Java 8 Optional<T>支持
    
  • 问题时间估算
    
• 进行API调用
  
  • 可用的子API

警告 如果您正在寻找我们的下一个主要版本6.x.x,它要求最低Java版本为11,并且使用jakarta.*包而不是javax.*包的Jakarta EE组件,请查看6.x分支。 如果您正在使用Spring Boot 3和Spring Framework 6.0,那么您需要的是6.x.x版本。

GitLab服务器版本支持

GitLab4J-API支持GitLab社区版(gitlab-ce)和GitLab企业版(gitlab-ee)的11.0+版本。

GitLab于2018年6月发布了GitLab 11.0版本,其中包含了对GitLab的许多重大更改。如果您使用的GitLab服务器版本早于11.0,强烈建议您要么更新GitLab安装,要么使用与您正在使用的GitLab版本大约同时发布的本库版本。

注意:
从GitLab 11.0开始,GitLab服务器已移除对GitLab API v3的支持(参见 https://about.gitlab.com/2018/06/01/api-v3-removal-impending/)。本库将在2019年某个时候移除对GitLab API v3的支持。如果您正在使用v3支持,请更新您的代码以使用GitLab API v4。

使用GitLab4J-API

Java 8要求

从GitLab4J-API 4.8.0开始,现在需要Java 8+才能使用GitLab4J-API。

Javadocs

Javadocs可在此处获取:

项目设置

要在Java项目中使用GitLab4J™ API,只需将以下依赖项添加到项目的构建文件中:
Gradle: build.gradle

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

注意: 使用4.5之前的Gradle版本拉取依赖项可能会失败。请参阅Gradle问题3065

Maven: pom.xml

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

Jbang:

Jbang非常方便运行依赖第三方库的Java脚本。

只需在脚本顶部添加此行:

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

Ivy和SBT
有报告称使用Ivy或SBT解析某些依赖项时存在问题,要解决这些问题,请参阅:
JAX-RS API问题#571
JAX-RS API问题#572

最新版本

虽然我们经常创建发布版本,但您可能对尚未发布的功能感兴趣。 您可以使用jitpack创建的jar来获取最新版本。

Gradle用法:

repositories {
    mavenCentral()
    maven {
        url "https://jitpack.io"
        content {
            includeGroup "com.github.gitlab4j"
        }
    }
}

dependencies {
    // ...
    implementation 'com.github.gitlab4j:gitlab4j-api:main-SNAPSHOT'
    // ...
}

Maven用法:

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.gitlab4j</groupId>
    <artifactId>gitlab4j-api</artifactId>
    <version>main-SNAPSHOT</version>
  </dependency>
  <!-- ... -->
</dependencies>

Jbang用法:

您只需像这样声明依赖项,而不是使用Maven坐标:

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

使用特定提交

版本main-SNAPSHOT表示您希望获取main分支的最新版本。 您也可以指向特定的提交:

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

<dependency>
    <groupId>com.github.gitlab4j</groupId>
    <artifactId>gitlab4j-api</artifactId>
    <version>6561c93aaf</version>
</dependency>

//DEPS https://github.com/gitlab4j/gitlab4j-api/tree/6561c93aafa6bf35cb9bad0617127a0c249a8f9f

使用示例

GitLab4J-API使用起来非常简单,您只需要GitLab服务器的URL和GitLab账户设置页面中的个人访问令牌。一旦有了这些信息,使用起来就像这样简单:

// 创建GitLabApi实例以与您的GitLab服务器通信
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.server.com", "YOUR_PERSONAL_ACCESS_TOKEN");

// 获取您的账户有权访问的项目列表
List<Project> projects = gitLabApi.getProjectApi().getProjects();

您也可以使用用户名和密码登录GitLab服务器:

// 使用用户名和密码登录GitLab服务器
GitLabApi gitLabApi = GitLabApi.oauth2Login("http://your.gitlab.server.com", "username", "password");

从GitLab4J-API 4.6.6开始,所有API请求都支持以另一个用户的身份执行API调用,前提是您以管理员身份进行身份验证:

// 创建GitLabApi实例以与您的GitLab服务器通信(必须是管理员)
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.server.com", "YOUR_PERSONAL_ACCESS_TOKEN");

// 以不同用户身份执行sudo,在本例中是名为"johndoe"的用户,所有后续调用都将以"johndoe"的身份执行
gitLabApi.sudo("johndoe")

// 关闭sudo模式
gitLabApi.unsudo();

设置请求超时

从GitLab4J-API 4.14.21开始,添加了对设置API客户端连接和读取超时的支持:

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

// 将连接超时设置为1秒,读取超时设置为5秒
gitLabApi.setRequestTimeout(1000, 5000);

通过代理服务器连接

从GitLab4J-API 4.8.2开始,添加了通过HTTP代理服务器连接到GitLab服务器的支持:

</SOURCE_TEXT>
<SOURCE_TEXT>
// 使用代理服务器（带基本认证）登录GitLab服务器
Map<String, Object> proxyConfig = ProxyClientConfig.createProxyClientConfig(
        "http://your-proxy-server", "proxy-username", "proxy-password");
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.com", "YOUR_PERSONAL_ACCESS_TOKEN", null, proxyConfig);

// 使用代理服务器（无认证）登录GitLab服务器
Map<String, Object> proxyConfig = ProxyClientConfig.createProxyClientConfig("http://your-proxy-server");
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.com", "YOUR_PERSONAL_ACCESS_TOKEN", null, proxyConfig);

// 使用NTLM（Windows DC）代理登录GitLab服务器
Map<String, Object> ntlmProxyConfig = ProxyClientConfig.createNtlmProxyClientConfig(
        "http://your-proxy-server", "windows-username", "windows-password", "windows-workstation", "windows-domain");
GitLabApi gitLabApi = new GitLabApi("http://your.gitlab.com", "YOUR_PERSONAL_ACCESS_TOKEN", null, ntlmProxyConfig);

有关接受代理配置的完整方法列表，请参阅GitLabApi类的Javadoc（clientConfiguration参数）

GitLab API V3和V4支持

从GitLab4J-API 4.2.0开始，已添加对GitLab API V4的支持。如果您的应用程序需要GitLab API V3， 您仍然可以通过以下方式创建GitLabApi实例来使用GitLab4J-API：

// 创建一个GitLabApi实例，使用GitLab API V3与您的GitLab服务器通信
GitLabApi gitLabApi = new GitLabApi(ApiVersion.V3, "http://your.gitlab.server.com", "YOUR_PRIVATE_TOKEN");

注意： 从GitLab 11.0开始，GitLab服务器已移除对GitLab API v3的支持（参见https://about.gitlab.com/2018/06/01/api-v3-removal-impending/）。对GitLab API v3的支持将在2019年某个时候从该库中移除。如果您正在使用v3支持，请更新您的代码以使用GitLab API v4。

API请求和响应的日志记录

从GitLab4J-API 4.8.39开始，已添加对记录GitLab API请求和响应的支持。使用GitLabApi实例的以下方法之一启用日志记录：

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

// 使用共享日志记录器和默认级别FINE进行日志记录
gitLabApi.enableRequestResponseLogging();

// 使用共享日志记录器和INFO级别进行日志记录
gitLabApi.enableRequestResponseLogging(java.util.logging.Level.INFO);

// 使用指定的日志记录器和INFO级别进行日志记录
gitLabApi.enableRequestResponseLogging(yourLoggerInstance, java.util.logging.Level.INFO);

// 使用共享日志记录器，INFO级别，并包括最多1024字节的实体日志记录
gitLabApi.enableRequestResponseLogging(java.util.logging.Level.INFO, 1024);

// 使用指定的日志记录器，INFO级别，并包括最多1024字节的实体日志记录
gitLabApi.enableRequestResponseLogging(yourLoggerInstance, java.util.logging.Level.INFO, 1024);

结果分页

GitLab4J-API提供了一种易于使用的分页机制，用于对GitLab API的结果列表进行分页。 以下是使用Pager的几个示例：

// 获取一个Pager实例，每页10个项目分页浏览项目
Pager<Project> projectPager = gitLabApi.getProjectApi().getProjects(10);

// 遍历页面并打印出名称和描述
while (projectPager.hasNext()) {
    for (Project project : projectPager.next()) {
        System.out.println(project.getName() + " -: " + project.getDescription());
    }
}

从GitLab4J-API 4.9.2开始，您还可以使用Pager实例将所有项目作为单个列表获取：

// 获取一个Pager实例，以便我们可以将所有项目加载到单个列表中，每次10个项目：
Pager<Project> projectPager = gitlabApi.getProjectsApi().getProjects(10);
List<Project> allProjects = projectPager.all();

Java 8流支持

从GitLab4J-API 4.9.2开始，所有返回List结果的GitLabJ-API方法都有一个类似命名的方法，返回Java 8流。返回流的方法使用以下命名约定：getXxxxxStream()。

重要 内置的返回流的方法使用___急切求值___，这意味着所有项目都从GitLab服务器预先获取，并返回一个将流式传输这些项目的流。急切求值不支持并行读取服务器数据，但它允许在数据获取后对流进行并行处理。

要使用___惰性求值___进行流式处理，请使用返回Pager实例的GitLab4J-API方法，然后在Pager实例上调用lazyStream()方法创建惰性求值流。该流利用Pager实例对可用项目进行分页。惰性流不支持并行操作或跳过。

急切求值示例用法：

// 流式处理可见项目，打印项目名称。
Stream<Project> projectStream = gitlabApi.getProjectApi().getProjectsStream();
projectStream.map(Project::getName).forEach(name -> System.out.println(name));

// 并行操作流，此示例按用户名对User实例进行排序
// 注意：用户的获取不是并行完成的，
// 只有用户的排序是并行操作。
Stream<User> stream = gitlabApi.getUserApi().getUsersStream();
List<User> users = stream.parallel().sorted(comparing(User::getUsername)).collect(toList());

惰性求值示例用法：

// 获取一个Pager实例，用于惰性流式处理Project实例。
// 在此示例中，每页将预取10个项目。
Pager<Project> projectPager = gitlabApi.getProjectApi().getProjects(10);

// 惰性流式处理项目，打印每个项目名称，将输出限制为5个项目名称
projectPager.lazyStream().limit(5).map(Project::getName).forEach(name -> System.out.println(name));

Java 8 Optional支持

GitLab4J-API支持Java 8 Optional用于返回单个项目的API调用。以下是如何使用Java 8 Optional API调用的示例：

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

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

问题时间估计

GitLab问题允许进行时间跟踪。目前可用的时间单位如下：

• 月（mo）
• 周（w）
• 天（d）
• 小时（h）
• 分钟（m）

转换率为1mo = 4w，1w = 5d，1d = 8h。

进行API调用

API已被分解为子API类，以便更容易使用并分离关注点。GitLab4J子API类通常与GitLab API文档有一对一的关系。以下是GitLab4J子API类与GitLab API文档映射的示例：

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

可用的子API

以下是可用子API的列表，以及每个API的示例用法。有关每个子API可用方法的完整列表，请参阅Javadocs。

  ApplicationsApi
  ApplicationSettingsApi
  AuditEventApi
  AwardEmojiApi
  BoardsApi
  CommitsApi
  ContainerRegistryApi
  DeployKeysApi
  DiscussionsApi
  EnvironmentsApi
  EpicsApi
  EventsApi
  GroupApi
  HealthCheckApi
  ImportExportApi
  IssuesApi
  JobApi
  LabelsApi
  LicenseApi
  LicenseTemplatesApi
  LabelsApi
  MergeRequestApi
  MilestonesApi
  NamespaceApi
  NotesApi
  NotificationSettingsApi
  PackagesApi
  PipelineApi
  ProjectApi
  ProtectedBranchesApi
  ReleasesApi
  RepositoryApi
  RepositoryFileApi
  ReourceLabelEventsApi
  RunnersApi
</SOURCE_TEXT> <SOURCE_TEXT> SearchApi
ServicesApi
SessionApi
SnippetsApi
SystemHooksApi
TagsApi
TodosApi
UserApi
WikisApi

子API示例

ApplicationsApi

// 向GitLab添加一个OAUTH应用
ApplicationScope[] scopes = {ApplicationScope.SUDO, ApplicationScope.PROFILE};
gitLabApi.getApplicationsApi().createApplication("我的OAUTH应用", "https//example.com/myapp/callback", scopes);

ApplicationSettingsApi

// 获取当前GitLab服务器的应用设置
ApplicationSettings appSettings = gitLabApi.getApplicationSettingsApi().getAppliationSettings();

AuditEventApi

// 获取实体的当前GitLab服务器审计事件
// 这里使用了org.gitlab4j.api.utils.ISO8601类中的ISO8601日期工具
Date since = ISO8601.toDate("2017-01-01T00:00:00Z");
Date until = new Date(); // 现在
List<AuditEvent> auditEvents = gitLabApi.getAuditEventApi().getAuditEvents(since, until, EntityType.USER, 1);

AwardEmojiApi

// 获取指定问题的AwardEmoji列表（群组ID = 1，问题IID = 1）
List<AwardEmoji> awardEmojis = gitLabApi.getAwardEmojiApi().getIssuAwardEmojis(1, 1);

BoardsApi

// 获取指定项目的问题看板列表
List<Board> boards = gitLabApi.getBoardsApi().getBoards(projectId);

CommitsApi

// 获取指定时间窗口内与指定分支关联的提交列表
// 这里使用了org.gitlab4j.api.utils.ISO8601类中的ISO8601日期工具
Date since = ISO8601.toDate("2017-01-01T00:00:00Z");
Date until = new Date(); // 现在
List<Commit> commits = gitLabApi.getCommitsApi().getCommits(1234, "new-feature", since, until);

ContainerRegistryApi

// 获取指定项目的注册表仓库列表
List<RegistryRepository> registryRepos = gitLabApi.ContainerRegistryApi().getRepositories(projectId);

DeployKeysApi

// 获取已认证用户的部署密钥列表
List<DeployKey> deployKeys = gitLabApi.getDeployKeysApi().getDeployKeys();

DiscussionsApi

// 获取指定合并请求的讨论列表
List<Discussion> discussions = gitLabApi.getDiscussionsApi().getMergeRequestDiscussions(projectId, mergeRequestIid);

EnvironmentsApi

// 获取指定项目的环境列表
List<Environment> environments = gitLabApi.getEnvironmentsApi().getEnvironments(projectId);

EpicsApi

// 获取请求的群组及其子群组的史诗列表
List<Epic> epics = gitLabApi.getEpicsApi().getEpics(1);

EventsApi

// 获取已认证用户的事件列表
Date after = new Date(0); // 纪元之后
Date before = new Date(); // 现在之前
List<Event> events = gitLabApi.getEventsApi().getAuthenticatedUserEvents(null, null, before, after, DESC);

GroupApi

// 获取您有权访问的群组列表
List<Group> groups = gitLabApi.getGroupApi().getGroups();

HealthCheckApi

// 获取活跃度端点健康检查结果。假设已按以下文档设置IP白名单：
// https://docs.gitlab.com/ee/administration/monitoring/ip_whitelist.html
HealthCheckInfo healthCheck = gitLabApi.getHealthCheckApi().getLiveness();

ImportExportApi

// 为指定的项目ID安排项目导出
gitLabApi.getImportExportApi().scheduleExport(projectId);

// 获取指定项目ID的项目导出状态
ExportStatus exportStatus = gitLabApi.getImportExportApi().getExportStatus(projectId);

IssuesApi

// 获取指定项目ID的问题列表
List<Issue> issues = gitLabApi.getIssuesApi().getIssues(1234);

JobApi

// 获取指定项目ID的作业列表
List<Job> jobs = gitLabApi.getJobApi().getJobs(1234);

LabelsApi

// 获取指定项目ID的标签列表
List<Label> labels = gitLabApi.getLabelsApi().getLabels(1234);

LicenseApi

// 检索当前许可证的信息
License license = gitLabApi.getLicenseApi().getLicense();

LicenseTemplatesApi

// 获取开源许可证模板列表
List<LicenseTemplate> licenses = gitLabApi.getLicenseTemplatesApi().getLicenseTemplates();

MergeRequestApi

// 获取指定项目的合并请求列表
List<MergeRequest> mergeRequests = gitLabApi.getMergeRequestApi().getMergeRequests(1234);

MilestonesApi

// 获取指定项目的里程碑列表
List<Milestone> milestones = gitLabApi.getMilestonesApi().getMilestones(1234);

NamespaceApi

// 获取名称或路径中包含"foobar"的所有命名空间
List<Namespace> namespaces = gitLabApi.getNamespaceApi().findNamespaces("foobar");

NotesApi

// 获取项目ID为1234，问题IID为1的问题备注列表
List<Note> notes = gitLabApi.getNotesApi().getNotes(1234, 1);

NotificationSettingsApi

// 获取当前全局通知设置
NotificationSettings settings = gitLabApi.getNotificationSettingsApi().getGlobalNotificationSettings();

PackagesApi

// 获取指定项目ID的所有包
List<Packages> packages = gitLabApi.getPackagesApi().getPackages(1234);

PipelineApi

// 获取指定项目ID的所有流水线
List<Pipeline> pipelines = gitLabApi.getPipelineApi().getPipelines(1234);

ProjectApi

// 获取可访问的项目列表
public List<Project> projects = gitLabApi.getProjectApi().getProjects();

// 创建一个新项目
Project projectSpec = new Project()
    .withName("my-project")
    .withDescription("我的演示项目。")
    .withIssuesEnabled(true)
    .withMergeRequestsEnabled(true)
    .withWikiEnabled(true)
    .withSnippetsEnabled(true)
    .withPublic(true);

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

ProtectedBranchesApi

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

ReleasesApi

// 获取指定项目的发布列表
List<Release> releases = gitLabApi.getReleasesApi().getReleases(projectId);

RepositoryApi

// 获取项目的仓库分支列表，按名称字母顺序排序
List<Branch> branches = gitLabApi.getRepositoryApi().getBranches(projectId);

// 在项目中按名称搜索仓库分支
List<Branch> branches = gitLabApi.getRepositoryApi().getBranches(projectId, searchTerm);

RepositoryFileApi

// 获取仓库中文件的信息（名称、大小等）和内容
RepositoryFile file = gitLabApi.getRepositoryFileApi().getFile("file-path", 1234, "ref");   

ResourceLabelEventsApi

// 获取指定合并请求的标签事件
List<LabelEvent> labelEvents = gitLabApi.getResourceLabelEventsApi()
        .getMergeRequestLabelEvents(projectId, mergeRequestIid);

RunnersApi

// 获取所有运行器
List<Runner> runners = gitLabApi.getRunnersApi().getAllRunners();

SearchApi

// 全局搜索项目
List<?> projects = gitLabApi.getSearchApi().globalSearch(SearchScope.PROJECTS, "要搜索的文本");

ServicesApi

// 激活/更新Slack通知服务
SlackService slackService =  new SlackService()
        .withMergeRequestsEvents(true)
        .withWebhook("https://hooks.slack.com/services/ABCDEFGHI/KJLMNOPQR/wetrewq7897HKLH8998wfjjj")
        .withUsername("GitLab4J");
gitLabApi.getServicesApi().updateSlackService("project-path", slackService);

SessionApi

// 登录GitLab服务器并获取会话信息
gitLabApi.getSessionApi().login("你的用户名", "你的邮箱", "你的密码");

SnippetsApi

// 获取已认证用户的代码片段列表
List<Snippet> snippets = gitLabApi.getSnippetsApi().getSnippets();

SystemHooksApi

// 获取已安装的系统钩子列表
List<SystemHook> hooks = gitLabApi.getSystemHooksApi().getSystemHooks();

TagsApi

// 获取指定项目ID的标签列表
List<Tag> tags = gitLabApi.getTagsApi().getTags(projectId);

TodosApi

// 获取当前用户所有待办事项的列表
List<Todo> todos = gitLabApi.getTodosApi().gePendingTodos();

UserApi

// 获取用户ID为1的用户信息
User user = gitLabApi.getUserApi().getUser(1);

// 创建一个新用户，不设置密码，将收到重置密码邮件
User userConfig = new User()
    .withEmail("jdoe@example.com")
    .withName("Jane Doe")
</SOURCE_TEXT>
<SOURCE_TEXT>
.withUsername("jdoe");
String password = null;
boolean sendResetPasswordEmail = true;
gitLabApi.getUserApi().createUser(userConfig, password, sendResetPasswordEmail);

WikisApi

// 获取项目wiki中的页面列表
List<WikiPage> wikiPages = gitLabApi.getWikisApi().getPages();

</SOURCE_TEXT>