在 gitlab ci/cd 环境中，当您的项目依赖于私有的 composer 包时，确保 ci 管道能够正确访问这些私有仓库是至关重要的。常见的场景是，您在 composer.json 中定义了对内部命名空间下私有 git 仓库的依赖：
{
"repositories": [
{
"type": "git",
"url": "git@gitlab.com:namespace/package.git"
}
],
"require": {
"namespace/package": "dev-master"
}
}为了让 CI/CD 能够通过 SSH 访问这些仓库，通常会在 .gitlab-ci.yml 中进行 SSH 密钥的配置。这包括安装 openssh-client、启动 ssh-agent、导入 SSH 私钥和公钥，并添加 gitlab.com 到 known_hosts。一个典型的配置片段可能如下所示：
image: registry.gitlab.com/namespace/project:1.0.0
stages:
- deploy
.setup_ssh: &setup_ssh
- 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client zip unzip -y )'
- eval $(ssh-agent -s)
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
- echo "$SSH_PUBLIC_KEY" > ~/.ssh/id_rsa.pub
- echo "$SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/id_rsa
- ssh-keyscan gitlab.com >> ~/.ssh/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-add ~/.ssh/id_rsa
.setup_composer: &setup_composer
- composer i -n
deploy to dev:
stage: deploy
script:
- *setup_ssh
- *setup_composer尽管上述 SSH 配置看似完整，但许多开发者仍然会遇到类似以下的错误信息，表明权限不足：
Cloning into bare repository '/root/.composer/cache/vcs/git-gitlab.com-namespace-package.git'... remote: remote: ======================================================================== remote: remote: The project you were looking for could not be found or you don't have permission to view it. remote: remote: ======================================================================== remote: fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
这种错误通常不是 SSH 配置本身的问题，而是 GitLab 部署密钥的权限范围所致。
解决方案：启用部署密钥到所有私有依赖仓库
问题根源在于，您为主项目添加的部署密钥（Deploy Key）虽然可以访问主项目本身，但它并不会自动获得对所有其依赖的私有仓库的访问权限。您需要手动在每一个作为 Composer 依赖的私有仓库中启用该部署密钥。
以下是详细的操作步骤：
确认主项目已配置部署密钥： 确保您在主项目的 Settings > Repository > Deploy keys 中添加了用于 CI/CD 的公钥。通常，这个密钥是从 CI/CD 变量 ($SSH_PUBLIC_KEY 和 $SSH_PRIVATE_KEY) 中获取的。
导航到私有依赖仓库： 对于 composer.json 中列出的每一个私有 Git 仓库（例如 namespace/package.git），您需要单独访问其 GitLab 页面。
启用部署密钥： 在该私有依赖仓库的页面中，导航到 Settings > Repository > Deploy Keys。
查找并启用现有密钥： 在 "Privately accessible deploy keys" 或类似的区域，您会看到一个列表，其中包含了可以被启用的部署密钥。找到您在主项目中使用的那个部署密钥（通常通过名称识别），然后点击其旁边的 "Enable" 按钮。
完成上述步骤后，当 CI/CD 管道再次运行时，它将能够通过已启用的部署密钥访问所有必要的私有 Composer 包，从而顺利完成 composer install 或 composer update 操作。
注意事项与最佳实践
- 权限最小化原则： 仅在真正需要访问的私有仓库中启用部署密钥，避免不必要的权限扩散。
- 密钥管理： 部署密钥是针对特定项目的，建议为不同的 CI/CD 场景或不同的项目组使用独立的部署密钥，以提高安全性。
- 阅读权限： 部署密钥通常只提供拉取（read-only）权限，这对于 Composer 依赖安装是足够的。如果需要推送权限，您可能需要考虑使用其他认证方式，例如项目访问令牌（Project Access Tokens）或群组访问令牌（Group Access Tokens）。
- 验证 known_hosts： 确保您的 CI 容器中的 ~/.ssh/known_hosts 文件包含了 GitLab.com 的 SSH 主机指纹，以避免首次连接时的安全警告。
通过正确配置和管理部署密钥，您可以确保 GitLab CI/CD 管道高效、安全地处理私有 Composer 包依赖，从而加速您的开发和部署流程。
