软件包仓库中的 Maven 软件包 - GitLab

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

在项目的软件包仓库中发布 Maven 产物。随后，可以在需要时将这些软件包安装为依赖项。

有关 Maven 软件包管理器客户端使用的特定 API 端点的文档，请参阅 Maven API 文档。

支持的客户端：

mvn。了解如何构建 Maven 软件包。
gradle。了解如何构建 Gradle 软件包。
sbt。

发布到极狐GitLab 软件包仓库#

认证到软件包仓库#

你需要一个令牌（token）才能发布软件包。根据你的目标，可用的令牌类型不同。有关更多信息，请查看关于令牌的指南。

创建一个令牌并保存，以便在后续流程中使用。

不要使用本文档未记载的认证方法。未记载的认证方法可能会在未来被移除。

编辑客户端配置#

更新你的配置，以通过 HTTP 向 Maven 仓库进行认证。

自定义 HTTP 标头#

你必须将认证详情添加到客户端的配置文件中。

令牌类型	名称必须为	令牌
个人访问令牌	Private-Token	原样粘贴令牌，或定义环境变量来保存令牌
部署令牌	Deploy-Token	原样粘贴令牌，或定义环境变量来保存令牌
CI 任务令牌	Job-Token	${CI_JOB_TOKEN}
OAuth 令牌	Authorization	在令牌前添加 Bearer 前缀（例如，Bearer <oauth_token>）

`` 字段必须与你选择的令牌类型匹配。

将以下部分添加到你的 settings.xml 文件中。

xml
1<settings>
2  <servers>
3    <server>
4      <id>gitlab-maven</id>
5      <configuration>
6        <httpHeaders>
7          <property>
8            <name>REPLACE_WITH_NAME</name>
9            <value>REPLACE_WITH_TOKEN</value>
10          </property>
11        </httpHeaders>
12      </configuration>
13    </server>
14  </servers>
15</settings>

令牌类型	名称必须为	令牌
个人访问令牌	Private-Token	原样粘贴令牌，或定义环境变量来保存令牌
部署令牌	Deploy-Token	原样粘贴令牌，或定义环境变量来保存令牌
CI 任务令牌	Job-Token	System.getenv("CI_JOB_TOKEN")
OAuth 令牌	Authorization	在令牌前添加 Bearer 前缀（例如，Bearer <oauth_token>）

`` 字段必须与你选择的令牌类型匹配。

在你的 GRADLE_USER_HOME 目录中，创建包含以下内容的 gradle.properties 文件：

properties
gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

将 repositories 部分添加到你的 build.gradle 文件中：

在 Groovy DSL 中：

groovy
1repositories {
2    maven {
3        url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
4        name "GitLab"
5        credentials(HttpHeaderCredentials) {
6            name = 'REPLACE_WITH_NAME'
7            value = gitLabPrivateToken
8        }
9        authentication {
10            header(HttpHeaderAuthentication)
11        }
12    }
13}

在 Kotlin DSL 中：

kotlin
1repositories {
2    maven {
3        url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
4        name = "GitLab"
5        credentials(HttpHeaderCredentials::class) {
6            name = "REPLACE_WITH_NAME"
7            value = findProperty("gitLabPrivateToken") as String?
8        }
9        authentication {
10            create("header", HttpHeaderAuthentication::class)
11        }
12    }
13}

基本 HTTP 认证#

你也可以使用基本 HTTP 认证向 Maven 软件包仓库进行认证。

令牌类型	名称必须为	令牌
个人访问令牌	用户的用户名	原样粘贴令牌，或定义环境变量来保存令牌
部署令牌	部署令牌的用户名	原样粘贴令牌，或定义环境变量来保存令牌
CI 任务令牌	gitlab-ci-token	${CI_JOB_TOKEN}

将以下部分添加到你的 settings.xml 文件中。

xml
1<settings>
2  <servers>
3    <server>
4      <id>gitlab-maven</id>
5      <username>REPLACE_WITH_NAME</username>
6      <password>REPLACE_WITH_TOKEN</password>
7      <configuration>
8        <authenticationInfo>
9          <userName>REPLACE_WITH_NAME</userName>
10          <password>REPLACE_WITH_TOKEN</password>
11        </authenticationInfo>
12      </configuration>
13    </server>
14  </servers>
15</settings>

令牌类型	名称必须为	令牌
个人访问令牌	用户的用户名	原样粘贴令牌，或定义环境变量来保存令牌
部署令牌	部署令牌的用户名	原样粘贴令牌，或定义环境变量来保存令牌
CI 任务令牌	gitlab-ci-token	System.getenv("CI_JOB_TOKEN")

在你的 GRADLE_USER_HOME 目录中，创建包含以下内容的 gradle.properties 文件：

properties
gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

将 repositories 部分添加到你的 build.gradle 中。

在 Groovy DSL 中：

groovy
1repositories {
2    maven {
3        url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
4        name "GitLab"
5        credentials(PasswordCredentials) {
6            username = 'REPLACE_WITH_NAME'
7            password = gitLabPrivateToken
8        }
9        authentication {
10            basic(BasicAuthentication)
11        }
12    }
13}

在 Kotlin DSL 中：

kotlin
1repositories {
2    maven {
3        url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
4        name = "GitLab"
5        credentials(BasicAuthentication::class) {
6            username = "REPLACE_WITH_NAME"
7            password = findProperty("gitLabPrivateToken") as String?
8        }
9        authentication {
10            create("basic", BasicAuthentication::class)
11        }
12    }
13}

令牌类型	名称必须为	令牌
个人访问令牌	用户的用户名	原样粘贴令牌，或定义环境变量来保存令牌
部署令牌	部署令牌的用户名	原样粘贴令牌，或定义环境变量来保存令牌
CI 任务令牌	gitlab-ci-token	sys.env.get("CI_JOB_TOKEN").get

SBT 的认证基于基本 HTTP 认证。你必须提供名称和密码。

名称字段必须与你选择的令牌类型匹配。

要通过 sbt 从 Maven 极狐GitLab 软件包仓库安装软件包，你必须配置一个 Maven 解析器。如果你访问的是私有或内部项目或群组，则需要设置凭证。配置好解析器和认证后，你可以从项目、群组或命名空间安装软件包。

在你的 build.sbt 中，添加以下行：

scala
resolvers += ("gitlab" at "<endpoint url>")

credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>")

在这个例子中：

<endpoint url> 是端点 URL。示例：https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven。
<host> 是 <endpoint url> 中的主机名，不包含协议方案或端口。示例：gitlab.example.com。
<name> 和 <token> 在上面的表格中进行了说明。

命名规范#

你可以使用三种端点之一来安装 Maven 软件包。你必须将软件包发布到项目，但选择的端点决定了添加到 pom.xml 文件中的发布设置。

这三种端点是：

项目：当你只有少量 Maven 软件包且它们不在同一个极狐GitLab 群组中时使用。
群组：当你想从同一极狐GitLab 群组中的多个不同项目安装软件包时使用。极狐GitLab 不保证群组内软件包名称的唯一性。你可能有两个项目具有相同的软件包名称和软件包版本。因此，极狐GitLab 会提供最新的那个。
实例：当你拥有许多分布在不同极狐GitLab 群组或各自命名空间中的软件包时使用。

对于实例级端点，请确保 Maven 中 pom.xml 的相关部分如下所示：

xml
  <groupId>group-slug.subgroup-slug</groupId>
  <artifactId>project-slug</artifactId>

只有与项目路径相同的软件包才会通过实例级端点公开。

项目	软件包	实例级端点可用
foo/bar	foo/bar/1.0-SNAPSHOT	是
gitlab-org/gitlab	foo/bar/1.0-SNAPSHOT	否
gitlab-org/gitlab	gitlab-org/gitlab/1.0-SNAPSHOT	是

端点 URL#

端点	pom.xml 的端点 URL	附加信息
项目	https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven	将 gitlab.example.com 替换为你的域名。将 <project_id> 替换为你的项目 ID，可在项目概览页面找到。
群组	https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven	将 gitlab.example.com 替换为你的域名。将 <group_id> 替换为你的群组 ID，可在群组首页找到。
实例	https://gitlab.example.com/api/v4/packages/maven	将 gitlab.example.com 替换为你的域名。

编辑用于发布的配置文件#

你必须将发布详情添加到客户端的配置文件中。

无论你选择哪种端点，都必须具备以下内容：

distributionManagement 部分中的项目特定 URL。
repository 和 distributionManagement 部分。

Maven 中 pom.xml 的相关 repository 部分应如下所示：

xml
1<repositories>
2  <repository>
3    <id>gitlab-maven</id>
4    <url><your_endpoint_url></url>
5  </repository>
6</repositories>
7<distributionManagement>
8  <repository>
9    <id>gitlab-maven</id>
10    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
11  </repository>
12  <snapshotRepository>
13    <id>gitlab-maven</id>
14    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
15  </snapshotRepository>
16</distributionManagement>

id 是你在 settings.xml 中定义的内容。
<your_endpoint_url> 取决于你选择的端点。
将 gitlab.example.com 替换为你的域名。

要使用 Gradle 发布软件包：

将 Gradle 插件 maven-publish 添加到插件部分：

在 Groovy DSL 中：

groovy
plugins {
    id 'java'
    id 'maven-publish'
}

在 Kotlin DSL 中：

kotlin
plugins {
    java
    `maven-publish`
}

添加 publishing 部分：

在 Groovy DSL 中：

groovy
1publishing {
2    publications {
3        library(MavenPublication) {
4            from components.java
5        }
6    }
7    repositories {
8        maven {
9            url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven"
10            credentials(HttpHeaderCredentials) {
11                name = "REPLACE_WITH_TOKEN_NAME"
12                value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties
13            }
14            authentication {
15                header(HttpHeaderAuthentication)
16            }
17        }
18    }
19}

在 Kotlin DSL 中：

kotlin
1publishing {
2    publications {
3        create<MavenPublication>("library") {
4            from(components["java"])
5        }
6    }
7    repositories {
8        maven {
9            url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven")
10            credentials(HttpHeaderCredentials::class) {
11                name = "REPLACE_WITH_TOKEN_NAME"
12                value =
13                    findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties
14            }
15            authentication {
16                create("header", HttpHeaderAuthentication::class)
17            }
18        }
19    }
20}

发布软件包#

使用 `DeployAtEnd` 选项可能导致上传被拒绝，返回 `400 bad request {"message":"Validation failed: Name has already been taken"}`。更多详情，请参见议题 424238。

完成认证并选择发布端点后，即可将 Maven 软件包发布到你的项目。

要使用 Maven 发布软件包：

shell
mvn deploy

如果部署成功，应显示构建成功消息：

shell
...
[INFO] BUILD SUCCESS
...

消息还应显示软件包已发布到正确位置：

shell
Uploading to gitlab-maven: https://example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar

运行发布任务：

shell
gradle publish

转到项目的 软件包与镜像仓库 页面，查看已发布的软件包。

在你的 build.sbt 文件中配置 publishTo 设置：

scala
publishTo := Some("gitlab" at "<endpoint url>")

确保正确引用了凭证。有关更多信息，请参见 sbt 文档。

要使用 sbt 发布软件包：

shell
sbt publish

如果部署成功，将显示构建成功消息：

shell
[success] Total time: 1 s, completed Jan 28, 2020 12:08:57 PM

检查成功消息以确保软件包已发布到正确位置：

shell
[info]  published my-project_2.12 to https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/my-project_2.12/0.1.1-SNAPSHOT/my-project_2.12-0.1.1-SNAPSHOT.pom

如果在发布之前对 Maven 软件包进行了保护，则该软件包将被拒绝，并返回 `403 Forbidden` 错误和 `Authorization failed` 错误消息。确保在发布时 Maven 软件包未被保护。有关软件包保护规则的更多信息，请参见 [如何保护软件包](../package_registry/package_protection_rules.md#protect-a-package)。

安装软件包#

要从极狐GitLab 软件包仓库安装软件包，你必须配置远程仓库并进行认证。完成后，即可从项目、群组或命名空间安装软件包。

如果多个软件包具有相同的名称和版本，安装时将获取最近发布的软件包。

要使用 mvn install 安装软件包：

手动将依赖项添加到项目的 pom.xml 文件中。例如，要添加之前创建的示例，XML 内容如下：

xml
<dependency>
  <groupId>com.mycompany.mydepartment</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

在项目中，运行以下命令：
```
shell
mvn install
```

消息应显示软件包正从软件包仓库下载：

shell
Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

你也可以直接使用 Maven dependency:get 命令安装软件包。

在项目目录中，运行：

shell
mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT -DremoteRepositories=gitlab-maven::::<gitlab endpoint url>  -s <path to settings.xml>

<gitlab endpoint url> 是极狐GitLab 端点的 URL。
<path to settings.xml> 是包含认证详情的 settings.xml 文件路径。

`gitlab-maven` 命令和 `settings.xml` 文件中的仓库 ID 必须匹配。

消息应显示软件包正从软件包仓库下载：

shell
Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

Maven 软件包的代理下载#

版本历史

在极狐GitLab 17.8 中引入。

极狐GitLab Maven 软件包仓库使用远程包含校验和。当你下载文件时，仓库会代理文件，并在一次请求中将文件及其相关校验和发送给 Maven 客户端。

对较新的 Maven 客户端使用远程包含校验和：

减少客户端向极狐GitLab Maven 软件包仓库发出的网络请求数量。
降低极狐GitLab 实例的负载。
缩短客户端命令的执行时间。

由于技术限制，当你使用对象存储时，Maven 软件包仓库会忽略 packages 对象存储配置中的代理下载设置。相反，对于 Maven 软件包仓库下载，代理下载始终启用。

如果你不使用对象存储，此行为对你的实例没有影响。

Maven 软件包的 CI/CD 集成#

你可以使用 CI/CD 自动构建、测试和发布 Maven 软件包。本节中的示例涵盖了以下几个场景：

多模块项目
版本化发布
条件发布
与代码质量和安全扫描集成

你可以调整和组合这些示例，以满足特定项目需求。

请根据项目要求调整 Maven 版本、Java 版本和其他具体设置。此外，确保已正确配置发布到极狐GitLab 软件包仓库所需的凭证和设置。

基本 Maven 软件包构建与发布#

本示例配置了一个构建并发布 Maven 软件包的流水线：

yaml
1default:
2  image: maven:3.8.5-openjdk-17
3  cache:
4    paths:
5      - .m2/repository/
6      - target/
7
8variables:
9  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
10  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
11
12stages:
13  - build
14  - test
15  - publish
16
17build:
18  stage: build
19  script:
20    - mvn $MAVEN_CLI_OPTS compile
21
22test:
23  stage: test
24  script:
25    - mvn $MAVEN_CLI_OPTS test
26
27publish:
28  stage: publish
29  script:
30    - mvn $MAVEN_CLI_OPTS deploy
31  rules:
32    - if: $CI_COMMIT_BRANCH == "main"

具有并行任务的多模块 Maven 项目#

对于拥有多个模块的大型项目，你可以使用并行任务来加快构建过程：

yaml
1default:
2  image: maven:3.8.5-openjdk-17
3  cache:
4    paths:
5      - .m2/repository/
6      - target/
7
8variables:
9  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
10  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
11
12stages:
13  - build
14  - test
15  - publish
16
17build:
18  stage: build
19  script:
20    - mvn $MAVEN_CLI_OPTS compile
21
22test:
23  stage: test
24  parallel:
25    matrix:
26      - MODULE: [module1, module2, module3]
27  script:
28    - mvn $MAVEN_CLI_OPTS test -pl $MODULE
29
30publish:
31  stage: publish
32  script:
33    - mvn $MAVEN_CLI_OPTS deploy
34  rules:
35    - if: $CI_COMMIT_BRANCH == "main"

使用标签的版本化发布#

本示例在推送标签时创建版本化发布：

yaml
1default:
2  image: maven:3.8.5-openjdk-17
3  cache:
4    paths:
5      - .m2/repository/
6      - target/
7
8variables:
9  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
10  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

基于更改的条件发布#

此示例仅当特定文件发生更改时发布软件包：

yaml
1default:
2  image: maven:3.8.5-openjdk-17
3  cache:
4    paths:
5      - .m2/repository/
6      - target/
7
8variables:
9  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
10  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
11
12stages:
13  - build
14  - test
15  - publish
16
17build:
18  stage: build
19  script:
20    - mvn $MAVEN_CLI_OPTS compile
21
22test:
23  stage: test
24  script:
25    - mvn $MAVEN_CLI_OPTS test
26
27publish:
28  stage: publish
29  script:
30    - mvn $MAVEN_CLI_OPTS deploy
31  rules:
32    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
33      changes:
34        - pom.xml
35        - src/**/*

集成代码质量与安全扫描#

此示例将代码质量检查和安全扫描集成到流水线中：

yaml
1default:
2  image: maven:3.8.5-openjdk-17
3  cache:
4    paths:
5      - .m2/repository/
6      - target/
7
8variables:
9  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
10  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
11
12include:
13  - template: Security/SAST.gitlab-ci.yml
14  - template: Code-Quality.gitlab-ci.yml
15
16stages:
17  - build
18  - test
19  - quality
20  - publish
21
22build:
23  stage: build
24  script:
25    - mvn $MAVEN_CLI_OPTS compile
26
27test:
28  stage: test
29  script:
30    - mvn $MAVEN_CLI_OPTS test
31
32code_quality:
33  stage: quality
34
35sast:
36  stage: quality
37
38publish:
39  stage: publish
40  script:
41    - mvn $MAVEN_CLI_OPTS deploy
42  rules:
43    - if: $CI_COMMIT_BRANCH == "main"

实用提示#

发布同名或同版本的软件包#

当你发布一个与已存在软件包具有相同名称和版本的软件包时，新软件包的文件会被添加到现有软件包中。你仍可以使用 UI 或 API 访问和查看现有软件包的旧资产。

要删除旧版本的软件包，请考虑使用 Packages API 或 UI。

不允许重复的 Maven 软件包#

版本历史

在极狐GitLab 15.0 中，所需角色从开发者更改为维护者。
在极狐GitLab 17.0 中，所需角色从维护者更改为所有者。

要阻止用户发布重复的 Maven 软件包，可以使用 GraphQL API 或 UI。

在 UI 中：

在顶部栏中，选择 搜索或跳转到 并找到你的群组。
在左侧边栏中，选择设置 > 软件包与镜像仓库。
在 重复软件包 表格的 Maven 行中，关闭 允许重复 切换按钮。
可选。在例外文本框中，输入一个匹配要允许的软件包名称和版本的正则表达式。

如果 **允许重复** 已打开，你可以在 **例外** 文本框中指定不应有重复的软件包名称和版本。

你的更改会自动保存。

请求转发到 Maven Central#

版本历史

在极狐GitLab 15.4 中引入，由一个名为 maven_central_request_forwarding 的功能标志控制。默认禁用。
在极狐GitLab 17.0 中，所需角色从维护者更改为所有者。

此功能的可用性由功能标志控制。更多信息，请参阅历史。

当在软件包仓库中找不到 Maven 软件包时，请求会被转发到 Maven Central。

当功能标志启用时，管理员可以在持续集成设置中禁用此行为。

Maven 转发仅限于项目级别和群组级别的端点。实例级别的端点存在命名限制，导致其无法用于不遵循该约定的软件包，并且还会为供应链式攻击带来过多安全风险。

为 mvn 进行额外配置#

使用 mvn 时，有多种方式来配置你的 Maven 项目，使其从极狐GitLab 请求 Maven Central 中的软件包。Maven 仓库按照特定顺序被查询。默认情况下，通常会通过 Super POM 首先检查 Maven Central，因此需要将极狐GitLab 配置为在 maven-central 之前被查询。

为确保所有软件包请求都被发送到极狐GitLab 而不是 Maven Central，你可以通过在你的 settings.xml 中添加一个 <mirror> 部分来覆盖 Maven Central 作为中央仓库：

xml
1<settings>
2  <servers>
3    <server>
4      <id>central-proxy</id>
5      <configuration>
6        <httpHeaders>
7          <property>
8            <name>Private-Token</name>
9            <value><personal_access_token></value>
10          </property>
11        </httpHeaders>
12      </configuration>
13    </server>
14  </servers>
15  <mirrors>
16    <mirror>
17      <id>central-proxy</id>
18      <name>极狐GitLab 代理中央仓库</name>
19      <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
20      <mirrorOf>central</mirrorOf>
21    </mirror>
22  </mirrors>
23</settings>

使用极狐GitLab CI/CD 创建 Maven 软件包#

在将仓库配置为使用 Maven 软件包仓库后，你可以配置极狐GitLab CI/CD 来自动构建新软件包。

你可以在每次默认分支更新时创建一个新软件包。

创建一个 ci_settings.xml 文件作为 Maven 的 settings.xml 文件。

添加 server 部分，其 ID 与你在 pom.xml 文件中定义的相同。例如，使用 gitlab-maven 作为 ID：

xml
1<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
3  <servers>
4    <server>
5      <id>gitlab-maven</id>
6      <configuration>
7        <httpHeaders>
8          <property>
9            <name>Job-Token</name>
10            <value>${CI_JOB_TOKEN}</value>
11          </property>
12        </httpHeaders>
13      </configuration>
14    </server>
15  </servers>
16</settings>

确保你的 pom.xml 文件包含以下内容。你可以根据需要，如本示例所示，让 Maven 使用预定义的 CI/CD 变量，也可以硬编码你的服务器主机名和项目 ID。

xml
1<repositories>
2  <repository>
3    <id>gitlab-maven</id>
4    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
5  </repository>
6</repositories>
7<distributionManagement>
8  <repository>
9    <id>gitlab-maven</id>
10    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
11  </repository>
12  <snapshotRepository>
13    <id>gitlab-maven</id>
14    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
15  </snapshotRepository>
16</distributionManagement>

将 deploy 作业添加到你的 .gitlab-ci.yml 文件中：

yaml
1deploy:
2  image: maven:3.6-jdk-11
3  script:
4    - 'mvn deploy -s ci_settings.xml'
5  rules:
6    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

将这些文件推送到你的仓库。

下一次 deploy 作业运行时，它会将 ci_settings.xml 复制到用户的主目录。在此示例中：

用户是 root，因为作业在 Docker 容器中运行。
Maven 使用配置的 CI/CD 变量。

你可以在每次默认分支更新时创建一个软件包。

使用 Gradle 中的 CI 作业令牌进行认证。

将 deploy 作业添加到你的 .gitlab-ci.yml 文件中：

yaml
1deploy:
2  image: gradle:6.5-jdk11
3  script:
4    - 'gradle publish'
5  rules:
6    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

提交文件到你的仓库。

当流水线成功时，Maven 软件包就会被创建。

版本验证#

版本字符串通过以下正则表达式进行验证。

ruby
\A(?!.*\.\.)[\w+.-]+\z

你可以在这个正则表达式编辑器中尝试该正则表达式并测试你的版本字符串。

为快照和发布部署使用不同的设置#

如需为快照和发布使用不同的 URL 或设置：

在 pom.xml 文件的 <distributionManagement> 部分中，分别定义 <repository> 和 <snapshotRepository> 元素。

有用的 Maven 命令行选项#

在使用极狐GitLab CI/CD 执行任务时，你可以使用一些 Maven 命令行选项。

文件传输进度可能会使 CI 日志难以阅读。选项 -ntp,--no-transfer-progress 在 3.6.1 中添加。或者，也可以查看 -B,--batch-mode 或更低级别的日志更改。

指定查找 pom.xml 文件的位置 (-f,--file)：

yaml
package:
  script:
    - 'mvn --no-transfer-progress -f helloworld/pom.xml package'

指定查找用户设置的位置 (-s,--settings)，而不是默认位置。还有 -gs,--global-settings 选项：
```
yaml
package:
  script:
    - 'mvn -s settings/ci.xml package'
```

支持的 CLI 命令#

极狐GitLab Maven 仓库支持以下 CLI 命令：

mvn deploy：将你的软件包发布到软件包仓库。
mvn install：安装你 Maven 项目中指定的软件包。
mvn dependency:get：安装特定软件包。

故障排除#

在极狐GitLab 中使用 Maven 软件包时，你可能会遇到问题。要解决许多常见问题，请尝试以下步骤：

验证认证 - 确保你的认证令牌正确且未过期。
检查权限 - 确认你拥有发布或安装软件包所需的权限。
验证 Maven 设置 - 仔细检查你的 settings.xml 文件配置是否正确。
查看极狐GitLab CI/CD 日志 - 对于 CI/CD 问题，请仔细检查作业日志中的错误信息。
确保使用正确的端点 URL - 验证是否使用了项目或群组的正确端点 URL。
在 mvn 命令中使用 -s 选项 - 始终在运行 Maven 命令时使用 -s 选项，例如 mvn package -s settings.xml。如果不使用此选项，认证设置将不会被应用，Maven 可能无法找到软件包。

清除缓存#

为了提高性能，客户端会缓存与软件包相关的文件。如果你遇到问题，请使用以下命令清除缓存：

shell
rm -rf ~/.m2/repository

shell
rm -rf ~/.gradle/caches # 或者将 ~/.gradle 替换为你自定义的 GRADLE_USER_HOME

查看网络跟踪日志#

如果你在使用 Maven 仓库时遇到问题，你可能希望查看网络跟踪日志。查看网络跟踪日志可提供更详细的错误信息，而这些信息在默认情况下是不包含在 Maven 客户端输出中的。

例如，尝试在本地使用 PAT 令牌运行 mvn deploy，并使用以下选项：

shell
mvn deploy \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace

当你设置这些选项时，所有网络请求都会被记录，并产生大量输出。

验证你的 Maven 设置#

如果在 CI/CD 中遇到与 settings.xml 文件相关的问题，请尝试添加一个额外的脚本任务或作业来验证生效的设置。

帮助插件也可以提供系统属性，包括环境变量：

yaml
1mvn-settings:
2  script:
3    - 'mvn help:effective-settings'
4
5package:
6  script:
7    - 'mvn help:system'
8    - 'mvn package'

尝试发布软件包时出现 401 Unauthorized 错误#

这通常表示认证问题。请检查：

你的认证令牌有效且未过期。
你使用了正确的令牌类型（个人访问令牌、部署令牌或 CI 作业令牌）。
令牌具有必要的权限（api、read_api 或 read_repository）。
对于 Maven 项目，你在 mvn 命令中使用了 -s 选项（例如 mvn deploy -s settings.xml）。如果不使用此选项，Maven 不会应用 settings.xml 文件中的认证设置，从而导致未经授权的错误。

400 Bad Request 错误，提示 "Validation failed: Version is invalid"#

极狐GitLab 对版本字符串有特定要求。请确保你的版本遵循以下格式：

plaintext
^(?!.*\.\.)(?!.*\.$)[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*(\+[0-9A-Za-z-]+)?$

例如，"1.0.0"、"1.0-SNAPSHOT" 和 "1.0.0-alpha" 是有效的，但 "1..0" 或 "1.0." 无效。

尝试发布软件包时出现 403 Forbidden 错误#

返回 403 Forbidden 错误并附带消息 Authorization failed 通常表示认证或权限问题。请检查：

你使用了正确的令牌类型（个人访问令牌、部署令牌或 CI/CD 作业令牌）。更多信息，请参见认证到软件包仓库。
令牌具有必要的权限。只有具有开发者、维护者或所有者角色的用户才能发布软件包。更多信息，请参见极狐GitLab 权限。
你要发布的软件包没有受到推送保护规则的保护。有关软件包保护规则的更多信息，请参见如何保护软件包。

发布时出现 Artifact already exists 错误#

当你尝试发布一个已存在的软件包版本时会出现此错误。解决方法：

在发布前递增你的软件包版本。
如果你使用的是 SNAPSHOT 版本，请确保在配置中允许 SNAPSHOT 覆盖。

已发布的软件包未在 UI 中显示#

如果你刚刚发布了一个软件包，可能需要等待一段时间才会显示。如果仍然无法显示：

验证你是否具有查看软件包所需的权限。
通过查看 CI/CD 日志或 Maven 输出，检查软件包是否成功发布。
确保你查看的是正确的项目或群组。

Maven 仓库依赖冲突#

依赖冲突可以通过以下方式解决：

在你的 pom.xml 中明确定义版本。
使用 Maven 的依赖管理部分来控制版本。
使用 <exclusions> 标签来排除冲突的传递性依赖。

Unable to find valid certification path to requested target 错误#

这通常是 SSL 证书问题。解决方法：

确保你的 JDK 信任极狐GitLab 服务器的 SSL 证书。
如果使用自签名证书，请将其添加到 JDK 的信任库中。
作为最后的手段，你可以在 Maven 设置中禁用 SSL 验证。不建议在生产环境中使用。

No plugin found for prefix 流水线错误#

这通常意味着 Maven 无法找到该插件。解决方法：

确保在 pom.xml 中正确定义了该插件。
检查你的 CI/CD 配置是否使用了正确的 Maven 设置文件。
验证你的流水线是否有权限访问所有必要的仓库。