Django-Stubs项目中的PyPI自动化发布配置实践

在开源项目Django-Stubs中，团队最近实现了自动化发布流程，但在实际执行过程中遇到了PyPI配置问题。本文将详细介绍这一技术实践过程，帮助开发者理解如何正确配置PyPI以实现GitHub Actions的自动化发布。

背景与问题发现

Django-Stubs项目团队在引入自动化发布机制后，首次执行时遇到了PyPI认证失败的问题。错误信息显示"invalid-publisher"，表明虽然令牌有效，但缺少对应的发布者配置。这一现象在尝试执行release.yml工作流时出现。

问题根源分析

经过排查，发现问题的根本原因在于PyPI端的"可信发布者"配置缺失。PyPI要求项目明确授权GitHub Actions工作流作为可信发布者，这是PyPI引入的一项安全措施，旨在防止未经授权的发布行为。

解决方案实施

项目维护者需要按照以下步骤在PyPI端完成配置：

1. 登录PyPI项目设置页面
2. 添加新的可信发布者
3. 填写以下关键信息：
   • 所有者：typeddjango
   • 仓库名称：django-stubs
   • 工作流名称：release.yml
   • 环境名称：release

配置完成后，系统会验证GitHub仓库和工作流的真实性，建立信任关系。这一过程确保了只有经过授权的GitHub Actions工作流才能向PyPI发布包。

多包发布策略讨论

在解决基础配置问题后，团队进一步讨论了django-stubs-ext包的发布策略。目前项目包含两个相关包：

1. django-stubs：核心包
2. django-stubs-ext：扩展包

经过讨论，团队达成以下共识：

• 保持两个包的版本号同步，避免维护复杂性
• 即使扩展包没有内容更新，也一并发布，确保版本一致性
• 简化发布流程，不增加额外的条件判断

这种策略虽然可能导致一些"空"发布，但大大简化了版本管理和发布流程，降低了出错概率。

技术实现建议

对于类似项目的自动化发布配置，建议：

1. 提前规划多包发布策略
2. 确保PyPI端的可信发布者配置完整
3. 考虑发布失败后的重试机制
4. 保持相关包的版本同步，减少维护负担

总结

Django-Stubs项目的这一实践展示了现代Python项目自动化发布的完整流程。通过正确配置PyPI可信发布者和制定合理的多包发布策略，团队成功建立了可靠的持续交付管道。这一经验对于其他需要管理多个相关Python包的项目具有很好的参考价值。