问题背景与常见误区
在gitlab ci/cd流水线中，当项目依赖于私有的composer包（或其他通过git协议拉取的私有依赖）时，常见的做法是配置ssh密钥以允许ci runner访问gitlab仓库。这通常涉及以下步骤：
- 生成SSH密钥对。
- 将公钥添加为GitLab项目（或用户）的部署密钥/SSH密钥。
- 在.gitlab-ci.yml中设置SSH代理，并将私钥注入CI环境变量。
尽管这些步骤对于访问主项目本身或其直接的公开依赖是有效的，但当遇到私有Composer包（如namespace/package）时，composer install命令可能会失败并报错，提示“项目未找到或您没有查看权限”。这通常是因为CI Runner虽然能够通过SSH连接到gitlab.com，但它所使用的身份（即部署密钥）并未被授权访问作为依赖的私有仓库。
一个常见的误区是认为只要主项目拥有部署密钥，其CI环境就能自动访问所有同命名空间下的私有仓库。然而，GitLab的权限模型更为细致：部署密钥是针对特定项目启用的。
解决方案：为每个私有依赖仓库启用部署密钥
解决此问题的关键在于，您需要为主项目使用的部署密钥在每个作为依赖的私有仓库中进行显式启用。 这确保了CI Runner在尝试克隆这些私有依赖时，其携带的身份（即部署密钥）被这些依赖仓库所识别并授权。
具体操作步骤如下：
确认主项目的部署密钥： 确保您的主项目（即运行CI流水线的项目）已经配置了部署密钥。通常，这个密钥的公钥会被添加到主项目的“部署密钥”设置中。
定位私有依赖仓库： 识别所有在composer.json中被依赖的私有Git仓库（例如，gitlab.com:namespace/package.git）。
-
在每个私有依赖仓库中启用部署密钥：
- 导航到每个私有依赖仓库的GitLab页面。
- 进入该仓库的 设置 (Settings) > 仓库 (Repository)。
- 找到 部署密钥 (Deploy Keys) 部分。
- 在“可私有访问的部署密钥 (Privately accessible deploy keys)”列表中，找到并勾选您在主项目上使用的那个部署密钥。点击“启用 (Enable)”或“添加密钥 (Add Key)”按钮（具体措辞可能因GitLab版本而异）。
通过此操作，您实际上是告诉GitLab，这个特定的部署密钥（由您的CI Runner使用）被允许访问当前的私有依赖仓库。
示例：.gitlab-ci.yml 中的SSH配置
尽管上述权限配置是在GitLab Web界面中完成的，但.gitlab-ci.yml中正确的SSH配置是其生效的前提。以下是一个典型的SSH配置片段：
image: registry.gitlab.com/namespace/project:1.0.0
stages:
- deploy
.setup_ssh: &setup_ssh
# 检查ssh-agent，如果不存在则安装openssh-client
- 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client zip unzip -y )'
# 启动ssh-agent
- eval $(ssh-agent -s)
# 创建并设置SSH目录权限
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
# 将SSH公钥和私钥写入文件
# SSH_PUBLIC_KEY 和 SSH_PRIVATE_KEY 应作为CI/CD变量安全存储
- echo "$SSH_PUBLIC_KEY" > ~/.ssh/id_rsa.pub
- echo "$SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/id_rsa
# 添加gitlab.com到known_hosts以避免首次连接时的确认
- ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
# 可选：如果还有其他自定义的Git主机，也添加到known_hosts
# - ssh-keyscan $DEV_HOST >> ~/.ssh/known_hosts
# 设置密钥文件权限
- chmod 600 ~/.ssh/id_rsa
- chmod 600 ~/.ssh/id_rsa.pub
- chmod 644 ~/.ssh/known_hosts
# 将私钥添加到ssh-agent
- ssh-add ~/.ssh/id_rsa
.setup_composer: &setup_composer
- composer i -n # -n 表示非交互模式
deploy to dev:
stage: deploy
script:
- *setup_ssh # 引用SSH设置
- *setup_composer # 运行Composer安装注意事项：
- SSH_PUBLIC_KEY 和 SSH_PRIVATE_KEY 应该是您在GitLab中配置的部署密钥的公钥和私钥。它们应该作为“受保护”的CI/CD变量存储在项目的设置中，以确保安全性。
- base64 -d 用于解码私钥，因为私钥通常为了避免换行符问题而以Base64编码存储在CI/CD变量中。
- ssh-keyscan 用于将GitLab服务器的公钥添加到known_hosts文件中，防止首次连接时出现主机密钥验证提示，从而确保CI流水线的自动化执行。
总结与最佳实践
解决GitLab CI中私有Composer包权限问题的核心在于理解部署密钥的作用范围。它并非全局生效，而是需要针对每个需要访问的私有仓库进行明确的授权。
关键点回顾：
- 部署密钥的独立性： 每个GitLab项目（包括作为依赖的私有包）都有自己的部署密钥管理。
- 显式启用： 必须在所有被依赖的私有仓库中，将主项目使用的部署密钥进行显式启用。
- 安全性： 将SSH私钥作为受保护的CI/CD变量存储，并使用base64 -d进行解码，确保密钥不直接暴露在.gitlab-ci.yml中。
- 可维护性： 考虑为不同环境（开发、测试、生产）使用不同的部署密钥，并为它们命名清晰，以便于管理。
通过遵循这些步骤，您可以确保GitLab CI流水线能够顺畅地访问和拉取所有必要的私有Composer包，从而实现自动化部署和构建。
