Using PyPI Trusted Publishing for Secure Package Uploads

Why Trusted Publishing matters for PyPI uploads

When you publish a package to PyPI you traditionally store a username and password (or an API token) in CI secrets. If those credentials are leaked, an attacker can push new versions, delete existing ones, or change metadata. Trusted Publishing replaces long‑lived credentials with short‑lived, scoped API tokens that you can create, rotate, and revoke without touching other account services.

Creating a scoped API token

Log in to PyPI, go to Account Settings → API tokens, and click Add API token. Choose a name that reflects its purpose (e.g., \"ci-upload\"). Under Scope select Upload only (or limit to a specific project if you maintain many). Optionally set a lifetime; leaving it blank creates a token that lives until you revoke it. Click Create token, copy the displayed value, and store it securely—PyPI will not show it again.

Using the token with twine

Most CI systems let you inject environment variables. The token is used as the password field; the username can be the literal string __token__. A typical snippet looks like:

# Example: set variables in a CI job
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgEIcH...   # replace with your actual token
twine upload dist/*

When the command runs, twine sends the token in the HTTP Basic auth header. If the token is valid and has upload scope, PyPI returns HTTP 200 and the package appears on the site.

Verifying the upload and revoking the token

1. Run the upload command; check the output for a successful status (HTTP 200 OK). No password prompt should appear.
2. In the PyPI web UI, return to Account Settings → API tokens, locate the token you just created, and click Revoke.
3. Run the upload again with the same environment variables. The command should fail with a 401 Unauthorized response, confirming that the token was the sole authentication method.

Trade‑offs and limitations

• Scope matters. An upload‑only token cannot delete packages or edit project metadata, but if you accidentally grant the Owner scope the token gains full account control.
• No automatic expiry. Unless you set a lifetime when creating the token, it remains valid until you manually revoke it. Forgotten tokens therefore pose a lingering risk.
• OIDC integration adds setup. To use federated identity you must configure your OIDC provider to issue tokens that PyPI trusts and map them to the appropriate scopes. This is powerful but requires extra configuration steps.

Adopting Trusted Publishing reduces secret sprawl, lets you rotate credentials without touching other services, and gives you fine‑grained control over what a CI system can do on PyPI. Create an upload‑only token today, test the flow, and make token revocation part of your CI cleanup routine.