如何使用极狐GitLab Maven 仓库？

本文作者：徐晓伟

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

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

文档

1. 软件包库中的 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​

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

  

群组ID

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

  

认证方式

在 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 依赖

1. 项目：https://gitlab.com/xuxiaowei-com-cn/my-maven-app/-/packages/
2. 已发布的依赖：https://gitlab.com/xuxiaowei-com-cn/my-maven-app/-/packages/
3. 极狐GitLab Runner 发布日志：https://gitlab.com/xuxiaowei-com-cn/my-maven-app/-/pipelines
4. 认证方式： 使用 Maven 中的 CI 作业令牌进行身份验证

5. 使用的配置

   1. setting.xml 配置

      1. setting.xml 配置
      2. setting.xml 配置 永久链

   2. pom.xml 配置

      1. pom.xml 配置
      2. pom.xml 配置 永久链

使用 Maven 依赖

1. 项目：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app
2. GitLab Runner 打包日志：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/pipelines

3. 打包失败：

   1. 失败日志 

   2. 失败原因：

      1. 没有设置凭证，无法访问非公开的软件包库
      2. 设置了凭证，但该凭证没有权限访问软件包库

4. 成功示例：

   1. main 分支：

      1. 代码：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/tree/6...
      2. 流水线：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/pipeli...
      3. 作业：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/jobs/5...

   2. delete-server 分支：

      1. 代码：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/tree/f...
      2. 流水线：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/pipeli...
      3. 作业：https://gitlab.com/xuxiaowei-com-cn/use-my-maven-app/-/jobs/5...

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

1. 文档依据（注意：中文版可能会比英文版的文档版本低，参见文档右上角）

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

解决方案2：不设置 setting.xml 的 server

1. 如果你的依赖项目是公开的， 软件包库是公开的，可以不使用 setting.xml 配置 server，即可访问
2. 如果你配置了 setting.xml 配置 server，使用方式为 使用 Maven 中的 CI 作业令牌进行身份验证， 参考上一个解决方案

解决方案3：在 Maven 中使用个人访问令牌进行身份验证

解决方案4：在 Maven 中使用部署令牌进行身份验证

gitlab 17.0 会删除上述【允许来自以下项目的 CI 作业令牌访问此项目】的，待 gitlab 17.0 发布后，将会提供新方案

问题

maven 证书验证失败链接")

1. 常见于自建 gitlab 中
2. 失败示例 
3. 打包时增加参数

参数	解释0	说明
-Dmaven.wagon.http.ssl.insecure=true	不要验证SSL证书的有效性

号外号外！
极狐GitLab 正在推出DevSecOps 成熟度测评！链接：https://gitlab.cn/devsecops-assessment/ 测评非常全面并提供了可靠建议，即使不付费买产品，对自己想要落地 DevSecOps 的用户具有很高的参考意义！快来动手试试吧！