Docker Build-Push Action中处理Git子模块的权限问题解析

问题背景

在使用Docker Build-Push Action进行容器构建时，当代码仓库中包含指向其他仓库的Git子模块时，构建过程经常会遇到权限拒绝的错误。典型错误表现为"[e-mail]: Permission denied (publickey)"，导致无法从远程仓库读取子模块内容。

问题本质

这个问题的根源在于Docker Build-Push Action默认会自动执行代码仓库的检出(checkout)操作，但对于包含子模块的仓库，特别是当子模块指向私有仓库时，默认配置无法正确处理子模块的认证问题。

技术原理

Git子模块允许将一个Git仓库作为另一个Git仓库的子目录，这在大型项目中很常见，用于管理依赖或共享代码。当主仓库被克隆时，默认不会自动克隆子模块，需要显式指定递归克隆参数。

解决方案

目前有两种主要解决思路：

1. 使用Path上下文绕过默认检出
   通过配置Path上下文，可以完全控制代码检出过程，避免使用Build-Push Action的默认检出行为。这种方法需要用户自行处理整个检出流程，包括子模块的递归克隆。

2. 等待官方支持子模块参数
   社区已经提出需求，希望Build-Push Action能像GitHub的checkout action一样支持submodules参数，但目前尚未实现。

最佳实践建议

对于遇到此问题的用户，推荐采用Path上下文方案作为临时解决方案。具体实施时需要注意：

• 在workflow中先使用标准的checkout action检出代码，并启用递归子模块
• 然后将检出后的目录路径传递给Build-Push Action
• 确保CI环境具有访问所有子模块所需的SSH密钥或访问令牌

未来展望

随着容器化开发中多仓库依赖的普及，预计Docker官方将会在后续版本中增加对子模块的原生支持，简化这一常见场景的配置流程。在此之前，Path上下文方案提供了可靠的替代方案。