How to allow/enable trusted publishing for Github project URLs on pypi.org project pages

[julian-smith-artifex-com]

I noticed that twine 6.1.0 introduced support for "Trusted publishing" to pypi.org; see https://twine.readthedocs.io/en/latest/changelog.html#twine-6-1-0-2025-01-17 and #1194.

It looks like it's supposed to work automatically, but i don't understand how to enable it. When i used twine a few weeks ago to upload to pypi.org with twine 6.2.0, it certainly didn't result in any Github urls on the project pages (e.g. https://pypi.org/project/PyMuPDF/) being listed as "Verified". And there were no diagnostics warning about a Trusted publishing failure.

For reference:

• Pymupdf's metadata includes Source, https://github.com/pymupdf/pymupdf.
• I currently use a pypi "API token" when uploading wheels to pypi.org, with twine -u __token__ -p <tokentext> ....

Could anyone advise what i need to do to allow pypi to verify that i have access to the Github repositories listed in the wheel metadata?

Thanks in advance.

[woodruffw]

Hi @julian-smith-artifex-com, please see https://docs.pypi.org/trusted-publishers/adding-a-publisher/

Once you've enrolled your publisher on PyPI, you can remove your API token from CI/CD and add id-token: write as a permission instead. From there, twine upload will perform the Trusted Publishing token exchange flow automatically.

[julian-smith-artifex-com]

Thanks, but i'm a bit confused.

I'm not uploading wheels by running twine in a Github action or similar. Instead i upload wheels by running twine on my local unix system.

So while we use Github to host the code (https://github.com/pymupdf/pymupdf), i don't use Github as a publisher. So i don't know how to fill in the Add a new publisher form - for example i don't have a relevant workflow name.

[woodruffw]

Trusted Publishing is specifically for CI; if you're publishing from a local or self-managed machine then using an API token is perfectly appropriate.

[julian-smith-artifex-com]

Ok, good to know thanks.

So how can i persuade pypi to make https://github.com/pymupdf/pymupdf show the Project links (e.g. the Source link to https://github.com/pymupdf/pymupdf) as "Verified"?

[woodruffw]

PyPI's verified links feature currently requires Trusted Publishing, since that's the only automatic way PyPI can cryptographically verify a link between a PyPI project and its source URLs. So unfortunately there's no real way to get locally published URLs marked as verified, since there's no way to verify them ATM.

(This might change in the future, but also note that URL verification doesn't affect a package in any positive or negative way.)

[julian-smith-artifex-com]

Ok, thanks for clarifying.

(I wonder whether the twine/pypi docs could be updated to include this information.)

[woodruffw]

No problem. There's some docs here that explain how links get verified, but feedback on them would be appreciated: https://docs.pypi.org/project_metadata/#verified-details

[julian-smith-artifex-com]

I did read these docs before, but unfortunately it wasn't clear to me that self-publishing would not work.

I can see now that the docs do at least imply that verifying requires that uploads are done from within github actions, gitlab ci/cd, google cloud or activestate.

But to an uninitiated reader, it would seem at least theoretically possible for pypi to be told to associate a particular pypi token with a separate secret that gives access to one or more github repositories. And this would allow URLs to be marked as verified. I think it was this possibility that contributed to my misunderstanding.

So i think it would help if there was an explicit statement somewhere similar to your statement that there's no real way to get locally published URLs marked as verified.

Maybe https://docs.pypi.org/trusted-publishers/ 's Quick background: Publishing with OpenID Connect could have an extra item in the enumerated list? For example:

5. Other publishing mechanisms, such as direct use of twine on a user machine, do not support Trusted Publishing.