成为赞助商——支持中文 Agent 生态

了解赞助
库Agent场景库
← 返回用例列表

PyPI Trusted Publishers(OIDC)发布简报

按 OIDC 短时身份、在项目 Publishing 绑定仓库/工作流、可选 GitHub Environment,整理无长期 API token 的正式发布简报;不代持凭据、不代上传。

场景说明

面向独立开发者:把「CI 用 Trusted Publisher 发正式 PyPI」写成可对账步骤,区别于 TestPyPI 试传与长期 token 保管。

案例叙事

01他们做了什么

独立开源或内部包要上正式 PyPI 时,常见麻烦是:把长期 API token 塞进 Actions secrets,轮换痛苦,泄漏面也大。

PyPI User Documentation《Trusted Publishing · Getting Started》说明:Trusted Publishing 指用 OpenID Connect(OIDC)在受信任的第三方服务与 PyPI 之间交换短时身份令牌,用于自动化环境,从而不必再用手工生成的长期 API token 鉴权上传。文档 TL;DR:部分 CI(如 GitHub Actions)可作为 OIDC 身份提供方签发可强校验来源的短时令牌;PyPI 项目可配置信任某一 CI 上的特定配置,使其成为该项目的 OIDC publisher;发布自动化向 PyPI 提交 OIDC 令牌,匹配成功后 PyPI 为对应项目签发短时 API token 再返回。快速入口包括:给已有项目添加 Trusted Publisher、用 Trusted Publisher 创建项目,以及实际发布步骤。配套《Adding a Trusted Publisher to an Existing PyPI Project》写明:在 Your projects 管理页进入 Publishing,按平台填写信任信息;GitHub Actions 必须提供仓库 owner 名、仓库名、授权上传的 workflow 文件名,并可选用 GitHub Actions environment——可选但强烈建议,以便对可信工作流再加人工审批等限制。本场景据此输出正式发布信任配置简报。禁止声称「已绑定成功」或代存任何 token。

02实际效果

  • 源未披露量化「相对长期 token 的事故下降比例」;公开文只描述 OIDC 换短时 token、绑定字段与 Environment 建议。
  • 能把「仍塞长期 token / workflow 文件名写错 / 未开 Environment 审批」拆开提问。
  • 与 TestPyPI 试发布衔接清晰:先试索引,再上正式 Trusted Publisher。

03值得知道

  • 支持的 publisher 平台与字段以 PyPI 当前 Publishing 页为准(文档示例含 GitHub、Google Cloud、ActiveState、GitLab 等)。
  • OIDC 信任面取决于仓库与 workflow 权限;Environment 审批不能替代最小权限审查。
  • 上面写的是官方机制说明,不是你项目当前的 publisher 列表。

04可复制提示词

Trusted Publisher 绑定简报

你是 PyPI Trusted Publishing 助手。只给绑定与发布核对简报,不要编造已配置成功。

PyPI 项目名:{{project_name}}
GitHub owner/repo:{{github_repo}}
workflow 文件名:{{workflow_file}}
是否用 Environment:{{environment_plan}}
现状/报错:{{status_or_error}}

输出 Markdown:
1. 为何用 OIDC 替代长期 API token
2. Publishing 页必填字段核对
3. Environment 是否启用及审批提问
4. 首次发布验收步骤(人工)
禁止索要 API token 或 OIDC 原始断言;禁止代点 Add。

OIDC 发布失败排查提纲

CI 宣称 Trusted Publisher 发布失败,请写排查提纲。

工作流摘要:{{workflow_brief}}
PyPI 报错摘要:{{error}}
已登记 publisher 摘要(可打码):{{publisher_brief}}

输出:
1. owner/repo/workflow 是否与登记一致
2. Environment 名称是否匹配
3. 是否仍在用长期 token 旁路
4. 下一步人工核对
不要伪造「已上传到正式 PyPI」。

怎么做

  1. 粘贴项目名、GitHub 仓库/工作流文件名、是否计划用 Environment,以及当前报错或 Publishing 页摘要
  2. Agent 按官方 Trusted Publishing 说明输出:OIDC 动机→绑定字段→可选 Environment→发布时换短时 token 的提问清单
  3. 人工在 PyPI Publishing 页与 CI 完成配置;Agent 不代点 Add、不代跑 upload

实用提示

  • Trusted Publishing 用 OIDC 换短时身份,目标是去掉长期 API token;GitHub 需填 owner、repo、workflow 文件名,Environment 可选但强烈建议
  • 与 testpypi-upload-install-checklist 不同:本条是正式索引的 OIDC 发布信任,不是 TestPyPI 试装演练
#PyPI#Trusted Publishers#OIDC#GitHub Actions#独立开发者