使用python-gitlab创建子模块遇阻，求可行方案及替代方法

我之前在使用python-gitlab处理子模块的时候也踩过坑，这里给你分享两种可行的方案，一种是创建标准的Git子模块，另一种是GitLab平台层面的替代关联方法：

方法一：通过API创建.gitmodules文件（纯python-gitlab实现） #

Git子模块的核心是仓库根目录下的.gitmodules配置文件，python-gitlab没有专门的子模块操作API，但我们可以直接通过文件API来创建或更新这个文件，从而实现子模块的关联。

示例代码如下：

import gitlab

# 初始化GitLab实例连接
gl = gitlab.Gitlab('https://你的GitLab实例地址', private_token='你的访问令牌')
gl.auth()

# 获取你要添加子模块的目标项目（可以用项目ID或路径）
main_project = gl.projects.get('你的项目路径或ID')

# 定义子模块的配置内容，替换成你的实际信息
gitmodules_content = """[submodule "docs/submodule-docs"]
    path = docs/submodule-docs
    url = https://你的GitLab实例地址/用户名/子模块项目.git
"""

try:
    # 检查.gitmodules文件是否已存在，存在则更新
    existing_file = main_project.files.get(file_path='.gitmodules', ref='main')
    existing_file.content = gitmodules_content
    existing_file.save(branch='main', commit_message='更新子模块配置')
except gitlab.exceptions.GitlabGetError:
    # 文件不存在则创建新文件
    main_project.files.create({
        'file_path': '.gitmodules',
        'branch': 'main',
        'content': gitmodules_content,
        'commit_message': '添加子模块配置'
    })

执行这段代码后，你的GitLab项目就会包含子模块配置，用户克隆项目时需要执行git clone --recurse-submodules，或者克隆后运行git submodule init && git submodule update来拉取子模块内容。

方法二：本地Git操作+python-gitlab辅助管理（适合已有本地仓库场景） #

如果你已经有本地仓库，更直观的方式是先用Git命令添加子模块，再提交推送，之后可以用python-gitlab处理后续的仓库操作（比如创建合并请求、触发CI等）：

1. 本地添加子模块：

git submodule add https://你的GitLab实例地址/用户名/子模块项目.git 本地存放路径

2. 提交子模块配置：

git add .gitmodules 本地存放路径
git commit -m "添加子模块：子模块项目名称"

3. 推送后，用python-gitlab可以做一些自动化操作，比如创建合并请求：

# 继续使用上面的main_project实例
mr = main_project.mergerequests.create({
    'source_branch': 'add-submodule',
    'target_branch': 'main',
    'title': 'Add submodule for docs',
    'description': '关联文档子模块到主项目'
})

替代方案：GitLab项目链接（无需修改Git树） #

如果你不需要在代码目录中包含子模块，只是想在GitLab平台层面关联两个项目，可以使用项目链接功能，这种方式不会修改仓库的Git结构：

示例代码：

# 获取要关联的子项目
sub_project = gl.projects.get('用户名/子模块项目')

# 创建项目关联，link_type可选值有related、forked_from、blocks、blocked_by等
main_project.links.create({
    'target_project_id': sub_project.id,
    'link_type': 'related'
})

创建后，在主项目的「Settings > Linked projects」页面就能看到关联的项目，方便团队成员快速跳转查看。

注意事项 #

• 如果子模块是私有项目，使用HTTPS URL时需要在地址中包含访问令牌，格式为https://oauth2:<你的令牌>@GitLab实例地址/用户名/子模块项目.git
• 用API创建.gitmodules后，子模块的空目录不会自动出现在仓库中，需要用户初始化子模块后才会生成
• 项目链接仅在GitLab平台生效，不会影响本地仓库的文件结构

内容的提问来源于stack exchange，提问作者XequinT