Improve error messages for Trusted Publishing

[facutuesca]

Is there an existing issue for this?

• I have searched the existing issues (open and closed), and could not find an existing issue

What keywords did you use to search existing issues?

error trusted publishing

Please describe the problem you are attempting to solve with this request

When twine upload fails in a Trusted Publishing scenario, the error messages are descriptive but could contain more information that would be useful to debug/solve the issue. For example, when using GH Actions and there's an error getting the OIDC token, twine says:

ERROR    TrustedPublishingFailure: Unable to retrieve an OIDC token from the CI
         platform for trusted publishing GitHub: missing or insufficient OIDC
         token permissions, the ACTIONS_ID_TOKEN_REQUEST_TOKEN environment
         variable was unset

In the case of GH Actions, we could say something like

ERROR    TrustedPublishingFailure: Unable to retrieve an OIDC token from GitHub
         Actions for trusted publishing.

         GitHub: missing or insufficient OIDC token permissions, the
         ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variable was unset

         This generally indicates a workflow configuration error, such as
         insufficient permissions. Make sure that your workflow has `id-token:
         write` configured at the job level, e.g.:

             permissions:
               id-token: write

         If this workflow was triggered by a pull request from a fork, note that
         GitHub does not grant OIDC permissions to those workflows, even when
         `id-token: write` is configured. Change the workflow to use an event
         that forks cannot trigger, such as a tag or release, or a manual
         workflow dispatch.

         Learn more at
         https://docs.pypi.org/trusted-publishers/using-a-publisher/

This is similar to what the official pypi-publish action does, and doing it in twine would allow the action to fully rely on twine for the Trusted Publishing flow, instead of implementing it from scratch. See the discussion here for more details.

How do you think we should solve this?

Modifying the error messages to be more descriptive, at least in the cases where we already know the likely issue (such as when publishing from GHA)

Anything else you'd like to mention?

No response

[woodruffw]

Seems reasonable to me. IMO twine's error messages here should be more detailed anyways, as a debugging aide 🙂

[webknjaz]

OTOH, I'm not entirely sure Twine should have runtime-specific instructions. It may end up having to implement instructions for every CI under the sun this way, which is probably beyond the scope, since TP is limited to what "certified/trusted".. There' may be a good case for separation. If Twine could output a generic TP troubleshooting message and a corresponding error code (or write a special file name to disk or something that the action would inspect), that would be enough to make it nice to work with.

[facutuesca]

OTOH, I'm not entirely sure Twine should have runtime-specific instructions. It may end up having to implement instructions for every CI under the sun this way, which is probably beyond the scope, since TP is limited to what "certified/trusted"

It would only be for the CI providers supported in Trusted Publishing, and it can be partial/gradual (e.g: one specific message for GHA, and a generic one for the rest, until someone is interested in making them more specific)

IMO the error messages are like documentation, and it's fine to have provider-specific information there (especially since twine can already distinguish between providers, via id's exceptions like GithubOidcPermissionCredentialError)

[woodruffw]

Yeah, my 0.0c is that it's fine to have more error detail here. Users can and do invoke twine upload directly from CI (i.e. without the action), so providing better error messages is a matter of better UX in those cases.