GitLab Runner中Poetry无法找到私有包安装候选问题排查

问题背景 #

使用同一GitLab实例的私有仓库和私有包注册表，本地通过个人访问令牌配置私有源后，可正常执行poetry add安装私有包my-private-package；但在GitLab CI流水线中，通过CI_JOB_TOKEN配置源并执行poetry install时，提示Unable to find installation candidates for my-private-package (0.0.8)。替换令牌为无效值会触发认证错误，说明认证流程正常，但无法定位到包资源。

相关配置文件 #

pyproject.toml #

[tool.poetry]
name = "my-project-name"
version = "0.0.1"
description = ""
authors = ["Eleanor <eleanor@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.group.dev.dependencies]
mypy = "^1.10.1"
pytest = "^8.2.2"
pycodestyle = "^2.12.0"
coverage = "^7.6.0"
pytest-html = "^4.1.1"
boto3-stubs = {extras = ["s3"], version = "^1.34.144"}
boto3 = "^1.34.144"
my-private-package = {version = "^0.0.8", source = "my-private-package-source"}

[[tool.poetry.source]]
name = "my-private-package-source"
url = "https://gitlab.private.gitlab.instance/api/v4/projects/9972/packages/pypi/simple"
priority = "explicit"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

.gitlab-ci.yml #

.poetry_setup:
  script:
    - !reference [.py_setup, script]
    - $pycommand -m pip install pipx
    - pipx_command="$pycommand -m pipx"
    - poetry_command="$pipx_command run poetry"
    - $poetry_command --version
    - !reference [.poetry_setup_sources, script]
    - $poetry_command install

.poetry_setup_sources:
  script:
    - $poetry_command config http-basic.my-private-package-source gitlab-ci-token $CI_JOB_TOKEN
    - $poetry_command config certificates.my-private-package-source.cert /cfs-certs.pem

错误日志 #

- Installing my-private-package (0.0.8)
  - Installing mypy (1.11.0)
  - Installing pytest-html (4.1.1)
  - Installing pycodestyle (2.12.0)
  RuntimeError
  Unable to find installation candidates for my-private-package (0.0.8)
  at ~/.cache/pipx/d2080b0cb8a1427/lib/python3.9/site-packages/poetry/installation/chooser.py:74 in choose_for
       70│ 
       71│             links.append(link)
       72│ 
       73│         if not links:
    →  74│             raise RuntimeError(f"Unable to find installation candidates for {package}")
       75│ 
       76│         # Get the best link
       77│         chosen = max(links, key=lambda link: self._sort_key(package, link))
       78│ 
Cannot install my-private-package.

排查方向与可能原因 #

1. CI_JOB_TOKEN权限不足 #

虽然认证通过，但CI_JOB_TOKEN默认仅能访问当前CI运行的项目资源，无法跨项目访问私有包：

• 登录GitLab目标包所在项目（ID 9972），进入设置 → 权限 → 项目成员，添加当前CI运行的项目为成员，赋予至少读取包注册表的权限；
• 检查当前项目的CI/CD设置，确认已启用CI_JOB_TOKEN对包注册表的访问权限（路径：设置 → CI/CD → 令牌权限，确保“包注册表”选项已勾选）。

2. 源配置匹配或加载问题 #

• 核对pyproject.toml中的源名称my-private-package-source与CI脚本中http-basic配置的名称是否完全一致（包括大小写、拼写）；
• 在CI脚本中添加$poetry_command source show my-private-package-source，确认源的URL、认证配置是否正确加载。

3. 包的平台/版本兼容性问题 #

本地与CI环境的Python版本、操作系统可能存在差异：

• 登录GitLab项目9972的包注册表，查看my-private-package 0.0.8是否上传了通用的sdist包或CI平台对应的wheel包（例如CI用Linux，但包仅上传了macOS的wheel）；
• 确认CI使用的Python版本是否符合包的版本约束（pyproject.toml中指定python = "^3.9"，需确保CI的Python版本在3.9.x范围内）。

4. 证书配置异常 #

CI中配置的证书文件可能不存在或无效：

• 在CI脚本中添加ls -l /cfs-certs.pem，确认文件存在且权限正常；
• 若GitLab实例使用公信任的SSL证书，可临时注释证书配置行，验证是否为证书导致的访问问题。

5. Poetry版本差异 #

本地与CI使用的Poetry版本不一致，可能导致源处理逻辑差异：

• 在CI脚本中指定与本地相同的Poetry版本安装，例如将pipx install poetry改为pipx install poetry==<本地版本号>；
• 对比本地与CI的poetry --version输出，确认版本一致。

6. 直接验证源访问 #

在CI脚本中添加curl命令，直接访问私有源的包路径，确认是否能获取到版本信息：

curl -u gitlab-ci-token:$CI_JOB_TOKEN https://gitlab.private.gitlab.instance/api/v4/projects/9972/packages/pypi/simple/my-private-package/

若返回为空或未包含0.0.8版本，说明源本身无法返回该包信息，需排查包的上传状态或项目权限。

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