如何使用极狐GitLab Maven 仓库？

本文作者：徐晓伟

GitLab 是一个全球知名的一体化 DevOps 平台，很多人都通过私有化部署 GitLab 来进行源代码托管。极狐GitLab 是 GitLab 在中国的发行版，专门为中国程序员服务。可以一键式部署极狐GitLab。

本文主要讲述了如何使用极狐GitLab 提供的Maven仓库功能。

文档

软件包库中的 Maven 包

Maven 仓库类型

项目级 Maven 端点


<project><repositories><repository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></repository></repositories><distributionManagement><repository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></repository><snapshotRepository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></snapshotRepository></distributionManagement>
</project>

群组级 Maven 端点


<project><repositories><repository><id>gitlab-maven</id><!-- GROUP_ID：填写群组ID，查看方式见下方 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven</url></repository></repositories><distributionManagement><repository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></repository><snapshotRepository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></snapshotRepository></distributionManagement>
</project>

实例级 Maven 端点


<project><repositories><repository><id>gitlab-maven</id><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/packages/maven</url></repository></repositories><distributionManagement><repository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></repository><snapshotRepository><id>gitlab-maven</id><!-- PROJECT_ID：填写项目ID，查看方式见下方 --><!-- PROJECT_ID：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_PROJECT_ID} 代替 --><!-- https://gitlab.example.com/api/v4：如果仅在 GitLab Runner 中运行时，可使用环境变量 ${CI_API_V4_URL} 代替 --><url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url></snapshotRepository></distributionManagement>
</project>

项目ID

截图来源于不同的 gitlab（gitlab 版本）中的项目，所以项目ID不同
同一个 gitlab 在不同位置查看到的项目ID是相同的

群组ID

截图来源于不同的 gitlab（gitlab 版本）版本中的项目，所以群组ID不同
同一个 gitlab 在不同位置查看到的群组ID是相同的

gitlab-51png

认证方式

在 Maven 中使用个人访问令牌进行身份验证


<settings><servers><server><id>gitlab-maven</id><configuration><httpHeaders><property><name>Private-Token</name><!-- 创建 gitlab 个人令牌，替换下方的值 --><value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value></property></httpHeaders></configuration></server></servers>
</settings>

在 Maven 中使用部署令牌进行身份验证


<settings><servers><server><id>gitlab-maven</id><configuration><httpHeaders><property><name>Deploy-Token</name><!-- 在仓库中创建部署令牌，替换下方的值 --><value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value></property></httpHeaders></configuration></server></servers>
</settings>

使用 Maven 中的 CI 作业令牌进行身份验证


<settings><servers><server><id>gitlab-maven</id><configuration><httpHeaders><property><name>Job-Token</name><!-- 此用法仅限于在使用 GitLab Runner 中执行使用 --><!-- 此处取 GitLab Runner 执行时的环境变量，用户无需干预此处的配置 --><value>${CI_JOB_TOKEN}</value></property></httpHeaders></configuration></server></servers>
</settings>

发布 Maven 依赖

项目：https://gitlab.com/xuxiaowei-com-cn/my-maven-app/-/packages/
已发布的依赖：https://gitlab.com/xuxiaowei-com-cn/my-maven-app/-/packages/
GitLab Runner 发布日志：https://gitlab.com/xuxiaowei-com-cn/my-maven-app/-/pipelines
认证方式：使用 Maven 中的 CI 作业令牌进行身份验证
使用的配置
1. setting.xml 配置
  1. setting.xml 配置
  2. setting.xml 配置永久链
2. pom.xml 配置
  1. pom.xml 配置
  2. pom.xml 配置永久链

使用 Maven 依赖

项目：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app
GitLab Runner 打包日志：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/pipelines
打包失败：
1. 失败日志
2. 失败原因：
  1. 没有设置凭证，无法访问非公开的软件包库
  2. 设置了凭证，但该凭证没有权限访问软件包库
成功示例：
1. main 分支：
  1. 代码：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/tree/6a71d280226ebb4aa16b479bc2b2d7a254f23513
  2. 流水线：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/pipelines/1118517218
  3. 作业：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/jobs/5818086715
2. delete-server 分支：
  1. 代码：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/tree/f493df00dd840f6cc39d89f2adb8e5c44a9ab75e
  2. 流水线：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/pipelines/1118518272
  3. 作业：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/jobs/5818091141

解决方案1：【允许来自以下项目的 CI 作业令牌访问此项目】

文档依据（注意：中文版可能会比英文版的文档版本低，参见文档右上角）
1. 限制您项目的作业令牌访问 - 中文
2. limit-your-projects-job-token-access - 英文
如果你的依赖项目不是公开的，软件包库不是公开的，需要使用 setting.xml 配置 server 标签填写访问凭证
如果使用的方式是使用 Maven 中的 CI 作业令牌进行身份验证，则需要在被引用的项目（my-maven-app）中设置【允许来自以下项目的 CI 作业令牌访问此项目】，填写引用项目（use-my-maven-app）的路径（不用填写域名），否则将会提示无权限
设置【允许来自以下项目的 CI 作业令牌访问此项目】