GitLab CI用Poetry通过PyPI API Token发包仍报403错误求助

原本采用用户名+密码认证的PyPI发布GitLab CI流水线因认证方式被弃用，出现403 Unauthorized错误。已按照指引创建项目级API Token，将PYPI_USERNAME设为__token__，PYPI_PASSWORD设为带pypi-前缀的Token值，但错误依旧。

流水线定义如下：

publish:package:
  stage: publish
  image: python:3.10.9-slim
  script:
    - apt-get update -y && apt-get install -y curl
    - curl -sSL https://install.python-poetry.org | python3 - --version 1.5.1
    - export PATH="/root/.local/bin:$PATH"
    - poetry build
    - poetry publish --username ${PYPI_USERNAME} --password ${PYPI_PASSWORD}
  only:
    - tags

可能的原因及解决方案 #

• Token权限不匹配
  项目级Token仅对关联的特定PyPI项目拥有权限，若你要发布的包名称与Token绑定的项目不一致，或Token未配置publish权限，会触发403错误。建议：

  • 确认Token的权限范围，确保包含目标包的发布权限；
  • 若需要发布多个包，改用账户级Token（拥有全账户下所有包的发布权限）。

• GitLab CI环境变量未生效
  GitLab的环境变量可能存在缓存，或你在错误的项目/群组层级更新了变量。检查：

  • 进入项目的设置 > CI/CD > 变量，确认PYPI_USERNAME值为__token__，PYPI_PASSWORD是完整的带pypi-前缀的Token；
  • 若变量设置了受保护，需确保流水线运行的分支/标签是受保护状态；
  • 临时取消变量的掩码设置测试（测试完成后恢复，避免敏感信息泄露）。

• Poetry版本兼容性问题
  你使用的Poetry 1.5.1版本可能对PyPI Token认证存在兼容缺陷。可以：

  • 升级Poetry到1.6.x及以上版本，修改安装命令为：

    curl -sSL https://install.python-poetry.org | python3 - --version 1.6.1
    

  • 或改用twine替代Poetry完成发布，替换流水线的发布步骤：

    - pip install twine
    - twine upload dist/* --username ${PYPI_USERNAME} --password ${PYPI_PASSWORD}
    

• Token格式或复制错误
  若Token存在遗漏前缀、多余空格/换行的情况，会导致认证失败。可在流水线中临时添加验证步骤（测试后删除，避免泄露信息）：

  - echo "Username: ${PYPI_USERNAME}"
  - echo "Token prefix: ${PYPI_PASSWORD:0:5}"
  

  确认用户名是__token__，Token前缀为pypi-。

• PyPI仓库地址配置错误
  若Poetry的pyproject.toml中配置了自定义仓库（如TestPyPI），但你的Token是针对官方PyPI创建的，会导致认证失败。解决方法：

  • 检查pyproject.toml中的仓库配置，确保指向官方PyPI；
  • 或在发布时显式指定官方仓库：

    - poetry publish --username ${PYPI_USERNAME} --password ${PYPI_PASSWORD} --repository pypi
    

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