Switch to Trusted Publishing for PyPI uploads

[woodruffw]

Hi there! Thanks for maintaining httpx.

I'm opening this up to see if there's appetite/interest among the httpx maintainers for switching the PyPI publishing process to Trusted Publishing: https://docs.pypi.org/trusted-publishers/

TL;DR: Trusted Publishing is a way to publish from CI/CD (like GitHub Actions) without long-lived credentials. It's already used by tens of thousands of packages on PyPI.

The main advantage to Trusted Publishing is that it doesn't require a manually configured credential in CI anymore, which means less credential exposure surface and operational churn. It also unblocks the ability to upload PEP 740 attestations for a package, since PEP 740 is established on top of the identities that Trusted Publishing uses internally.

In terms of the switch, I think httpx could do this pretty easily: you currently have a publish script that gets run from CI here:

httpx/.github/workflows/publish.yml

Lines 25 to 26 in ae1b9f6

	- name: "Publish to PyPI & deploy docs"
	run: "scripts/publish"

That script then invokes twine directly here:

httpx/scripts/publish

Line 25 in ae1b9f6

${PREFIX}twine upload dist/*

twine has native support for Trusted Publishing as of 6.1.0, so switching should be as simple as removing your credentials from CI, configuring the publisher on PyPI, and adding id-token: write to the CI job instead.

Alternatively, you could use uv publish or gh-action-pypi-publish, both of which also support Trusted Publishing.

Alternatives

The main alternative is to do nothing! API tokens aren't bad or broken; Trusted Publishing is just an improvement over them for the CI setting.

The main downside (for some projects) to Trusted Publishing is that it's limited to CI, i.e. you can't do local publishes with it. This is intentional, but it may not fit your publishing pattern, in which case you may not want to adopt it. However, if you do prefer publishing from CI (which is generally recommended as an isolation measure), then Trusted Publishing is a good fit.

Prior art

There's a lot of prior art out there, but here's an example of black switching: psf/black#4611

There's also a full official guide from PyPA on publishing from GitHub here: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

[amasen02]

Benefits & Implementation Blueprint for Trusted Publishing in httpx

Adopting PyPI Trusted Publishing (OIDC) is a massive security and operational improvement for httpx and the wider encode ecosystem. It eliminates long-lived repository secrets, removes credential rotation churn, and unblocks cryptographic build provenance (PEP 740).

Here is a practical breakdown of how this can be cleanly implemented in httpx's existing release workflow:

---

1. Key Architectural Benefits for httpx

1. Zero Credential Exposure: Eliminates the static PYPI_API_TOKEN secret from GitHub Actions secrets. Even if a workflow run or debug step is compromised, there are no reusable API tokens to extract.
2. Cryptographic Attestations (PEP 740): PyPI automatically generates and verifies build provenance using Sigstore. Downstream users and automated package managers (like pip and uv) can verify that the wheels on PyPI were built directly from the official encode/httpx release commit.
3. Environment Isolation: GitHub Actions Environments allow requiring manual maintainer approval before the publishing job runs on tag push.

---

2. Implementation: Workflow Update (publish.yml)

The primary requirement in GitHub Actions is adding the id-token: write permission so the runner can mint an ephemeral OIDC token for PyPI.

You can either keep twine (which supports Trusted Publishing natively via twine upload dist/* without --username or --password in CI) or use the official pypa/gh-action-pypi-publish action:

name: Publish

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  publish:
    name: Build & Publish to PyPI
    runs-on: ubuntu-latest
    # Crucial: Allows GitHub to generate the OIDC token for PyPI
    permissions:
      id-token: write
      contents: read
    environment:
      name: pypi
      url: https://pypi.org/p/httpx

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install build tools
        run: |
          python -m pip install --upgrade pip build twine

      - name: Build distribution packages
        run: |
          python -m build

      - name: Publish to PyPI via Trusted Publishing
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          # Generates PEP 740 cryptographic attestations automatically
          attestations: true

---

3. PyPI Setup Steps (One-time by maintainer)

1. Navigate to https://pypi.org/manage/project/httpx/settings/publishing/.
2. Add a new publisher:
   • Publisher: GitHub
   • Owner: encode
   • Repository name: httpx
   • Workflow name: publish.yml
   • Environment name: pypi
3. Remove the legacy PYPI_API_TOKEN from the repository secrets.