• 配置 .gitmodules 文件
  • 使用绝对 URL
  • 使用相对 URL
• 在 CI/CD 作业中使用 Git 子模块
• 故障排除
  • 找不到 .gitmodules 文件
  • fatal: run_command returned non-zero status 错误

{{< details >}}

• Tier: 基础版，专业版，旗舰版
• Offering: JihuLab.com，私有化部署

{{< /details >}}

使用 Git 子模块 将一个 Git 仓库作为另一个 Git 仓库的子目录。您可以将另一个仓库克隆到您的项目中，并保持您的提交独立。

配置 .gitmodules 文件

当您使用 Git 子模块时，您的项目应该有一个名为 .gitmodules 的文件。您有多种选项可以配置它以在极狐GitLab CI/CD 作业中工作。

使用绝对 URL

{{< history >}}

• 引入于极狐GitLab Runner 15.11。

{{< /history >}}

例如，您的生成的 .gitmodules 配置可能如下所示：

• 您的项目位于 https://gitlab.com/secret-group/my-project。
• 您的项目依赖于 https://gitlab.com/group/project，您希望将其作为子模块包含。
• 您使用 SSH 地址检查您的源代码，如 git@gitlab.com:secret-group/my-project.git。

[submodule "project"]
  path = project
  url = git@gitlab.com:group/project.git

在这种情况下，使用 GIT_SUBMODULE_FORCE_HTTPS 变量来指示 GitLab Runner 在克隆子模块之前将 URL 转换为 HTTPS。

或者，如果您本地也使用 HTTPS，您可以配置一个 HTTPS URL：

[submodule "project"]
  path = project
  url = https://gitlab.com/group/project.git

在这种情况下，您无需配置其他变量，但您需要使用 个人访问令牌 来本地克隆它。

使用相对 URL

{{< alert type=”warning” >}}

如果您使用相对 URL，在分叉工作流中子模块可能会解析不正确。请改用绝对 URL，如果您预计您的项目会有分叉。

{{< /alert >}}

当您的子模块在同一个极狐GitLab 服务器上时，您还可以在 .gitmodules 文件中使用相对 URL：

[submodule "project"]
  path = project
  url = ../../project.git

上述配置指示 Git 在克隆源代码时自动推断要使用的 URL。您可以在所有 CI/CD 作业中使用 HTTPS 克隆，并且可以继续使用 SSH 本地克隆。

对于不在同一个极狐GitLab 服务器上的子模块，请始终使用完整 URL：

[submodule "project-x"]
  path = project-x
  url = https://gitserver.com/group/project-x.git

在 CI/CD 作业中使用 Git 子模块

先决条件：

• 如果您在流水线作业中使用 CI_JOB_TOKEN 克隆子模块，您必须至少拥有子模块仓库的 Reporter 角色才能拉取代码。
• CI/CD 作业令牌访问必须在上游子模块项目中正确配置。

为了使子模块在 CI/CD 作业中正常工作：

1. 您可以将 GIT_SUBMODULE_STRATEGY 变量设置为 normal 或 recursive，以告诉 runner 在作业之前 获取您的子模块：

   variables:
     GIT_SUBMODULE_STRATEGY: recursive
   

2. 对于位于同一个极狐GitLab 服务器上的子模块，并使用 Git 或 SSH URL 配置的，请确保您设置了 GIT_SUBMODULE_FORCE_HTTPS 变量。

3. 使用 GIT_SUBMODULE_DEPTH 独立于 GIT_DEPTH 变量配置子模块的克隆深度：

   variables:
     GIT_SUBMODULE_DEPTH: 1
   

4. 您可以过滤或排除特定子模块来控制哪些子模块被同步使用 GIT_SUBMODULE_PATHS。

   variables:
     GIT_SUBMODULE_PATHS: submoduleA submoduleB
   

5. 您可以提供其他标志来控制高级签出行为使用 GIT_SUBMODULE_UPDATE_FLAGS。

   variables:
     GIT_SUBMODULE_STRATEGY: recursive
     GIT_SUBMODULE_UPDATE_FLAGS: --jobs 4
   

故障排除

找不到 .gitmodules 文件

.gitmodules 文件可能难以找到，因为它通常是一个隐藏文件。您可以查看特定操作系统的文档以了解如何找到和显示隐藏文件。

如果没有 .gitmodules 文件，可能子模块设置在 git config 文件中。

fatal: run_command returned non-zero status 错误

当处理子模块并且 GIT_STRATEGY 设置为 fetch 时，此错误可能发生在作业中。

将 GIT_STRATEGY 设置为 clone 应该能解决问题。