PyPI 发布前的手工准备

整理日期：2026-10-01。本文面向维护者，说明在生成库代码之前可以完成的账户注册、发布身份配置和资料准备。构建、质量检查和实际发布流程见 CI/CD 落地参考。

现在可以注册 PyPI 与 TestPyPI 账户、验证邮箱、启用双因素认证，并预先配置 GitHub 发布环境和 pending publisher（待启用发布者）。 后者允许首次通过 CI 上传时创建项目，但不预留包名。PyPI 新项目发布说明

当前已建立包构建、主分支 CI 和同批候选制品验收工作流。TestPyPI 显式手动发布可使用维护者提供的 API token，操作与验收见 CI/CD 落地参考，首次测试发布记录见 Issue #26。下文的 Trusted Publishing 仍是自动发布配置方案；建议值不表示账户、权限或发布者已经配置成功。

可以提前做什么

账户与环境准备可独立于代码生成进行；现在不需要上传空包来启动流程。

1. 注册两个独立账户

分别准备用户名、可长期访问的邮箱和密码；已有账户可直接使用。PyPI 用户名不需要与 GitHub 用户名或包名相同。TestPyPI 的账户和项目数据独立，不会从正式站同步；测试站数据也不适合用作长期发布记录。TestPyPI 官方说明

在每个站点完成以下操作：

1. 点击验证邮件中的链接，确认邮箱已验证。
2. 在账户设置启用双因素认证（2FA），使用认证器或支持的安全设备完成验证。
3. 生成恢复码并保存在自己的密码管理器或其他安全位置，确保更换设备后仍可恢复账户。

正式 PyPI 要求账户启用 2FA，创建项目或上传还需要已验证的邮箱。本项目在测试站也执行同样的准备步骤。PyPI 账户与认证帮助

密码、认证器密钥、恢复码及令牌均由维护者自行保管，不填入本文、GitHub Issue 或聊天。下面的交接内容只需要非敏感配置。

2. 确定包名与公开资料

以下值用于后续表单和 pyproject.toml，目前无需手写构建配置。

作者和公开联系邮箱属于可准备的展示资料，不是本项目要求注册账户时必须公开的凭据；具体元数据检查见 CI/CD 落地参考。

可查看 正式站的拟用项目地址 了解是否已有同名项目。即使页面不存在，也不能证明名称可用：名称可能被保留、被禁止或与已有项目冲突，最终由服务端判断。PyPI 名称帮助

pending publisher 不创建项目、不占有名称。 若其他人先创建同名项目，待启用配置会失效。首次发布前重新核对名称；若已是自己拥有的项目，使用下文的已有项目入口。pending publisher 的名称规则

3. 提前建立 GitHub 发布环境

建议本仓库使用以下命名，后续生成工作流时与手工配置保持一致：

打开仓库的 Settings → Environments，通过 New environment 分别创建两个环境。个人仓库需要所有者权限；组织仓库需要管理员权限。环境功能也取决于仓库可见性和 GitHub 套餐：公共仓库可用，当前仓库为私有，使用环境功能需要相应付费套餐；看不到入口时先核对这两项。GitHub 环境配置说明

针对本项目单人维护、直接在 main 开发的流程，建议初次接入采用以下设置：

• 两个环境的 Deployment branches and tags 选择 Selected branches and tags，添加类型为 Branch、名称为 main 的规则。
• 发布工作流先采用在 main 上显式手动触发的方式，并固定验收的提交；普通 main 推送只运行 CI。
• 如果后续采用版本 tag 触发，再增加类型为 Tag 的对应规则，例如 v*。工作流还须校验 tag 指向经完整验收的 main 提交；仅匹配 tag 名不足以保证来源正确。
• 不把第二名维护者审批作为发布前提，也不设置让唯一维护者无法完成发布的审批组合。这与当前主分支开发约定一致。

这里限制的是发布任务可以使用的环境，不改变日常直接推送 main 的方式。若套餐暂不支持环境，可先完成账户准备；环境字段在 PyPI 侧是可选项，但本方案建议保留，工作流落地时再明确可用配置，不把尚不存在的环境记作已验证。PyPI 环境字段说明

4. 分别填写 pending publisher

项目尚未创建时，登录后进入账户级入口：

• 正式站：PyPI → Publishing。
• 测试站：TestPyPI → Publishing。

选择 GitHub 发布者，按下表填写并添加。可以先约定工作流文件名，之后由 Codex 或 Claude Code 创建对应文件；无需为了配置发布身份先手工上传第一个包。PyPA 接入指南

Owner 是 GitHub 仓库所有者，不是 PyPI 用户名。仓库名只填 rpkiparrot，不带完整 URL 或 .git。Workflow name 填文件名 release.yml，不填完整路径，也不填 YAML 中 name: 的展示文字。环境名与相应发布任务的配置保持一致。PyPI 发布者字段说明

添加后，分别查看两个站点的 pending publisher 列表，逐项核对字段。配置存在只证明已登记发布身份；首次上传成功后，平台才会创建项目并将其转为常规发布者。若项目已经由自己的账户拥有，则从 Your projects → Manage → Publishing 为已有项目添加发布者，不再走 pending 入口。新项目入口、已有项目入口

此方案使用 Trusted Publishing，由 GitHub Actions 通过 OIDC 获取短期发布身份，无需预先创建 PYPI_API_TOKEN 或 TEST_PYPI_API_TOKEN secret。账户登录仍使用自己的 2FA；两者用途不同。PyPI Trusted Publishing

5. 将非敏感配置交给代码生成工具

手工准备后，可复制下面的表单填写实际结果，用于后续工程初始化。它是交接模板；本文不维护账户操作进度或代码功能待办。

正式分发名称：rpkiparrot（或实际选定名称）
GitHub 仓库：bgpglobal/rpkiparrot
发布工作流文件：release.yml（或实际填写值）
正式 / 测试环境名：pypi / testpypi（或实际填写值）
两个站点的邮箱验证与 2FA：待填写完成情况
两个环境及允许的分支 / tag：待填写实际配置
两个站点的 pending publisher：待填写是否已添加，或说明已有项目
公开署名：待填写
公开联系邮箱：待填写，或明确不公开
其他配置差异：待填写

仓库、工作流或环境后来改名时，同步核对平台中的 Trusted Publisher 配置，避免生成代码使用另一套值。库功能与发布流水线的待实现事项继续使用 GitHub Issues 跟踪。

代码与验收就绪后的发布流程

上述手工准备不能证明包可以发布。仓库已建立 pyproject.toml、源码布局、版本与许可元数据，并通过 nox -s package 提供本地及 CI 制品检查。实际发布按以下流程执行：

1. 核对最终提交的版本、许可、依赖及发布能力，执行已有构建与制品验收任务并保存报告。
2. 选择显式手动 token 上传或自动 Trusted Publishing。后者需创建约定的工作流，分开构建、验收与上传任务；只给需要获取发布身份的任务授予 id-token: write，并绑定对应环境。PyPA 发布工作流指南
3. 从明确的 main 提交构建真实 wheel 与 sdist，完成 CI/CD 落地参考 规定的检查，再进行首次 TestPyPI 演练。
4. 通过显式发布入口上传经过验收的同一批正式候选文件，检查项目页面、版本、下载哈希与干净环境安装；此时才能确认首次发布成功。

配置登记、测试站成功和正式站发布成功是不同的完成条件，应分别根据对应发布记录中的实际结果确认。