Python (PyPI)

Authenticate the release with OIDC trusted publishing (recommended) or a PyPI API token.

Enable publishing#

Turn on Publish to PyPI on merge, or add a publish block:

{
  "targets": {
    "python": {
      "packageName": "acme",
      "projectName": "acme-api",
      "publish": { "pypi": true }
    }
  }
}

Trusted publishing (OIDC)#

Recommended. PyPI exchanges the workflow's identity token for a short-lived upload token, so no secret is stored.

Add a trusted publisher on PyPI

On pypi.org, open your project's Publishing tab (for a brand-new project, use Your account → Publishing → Add a pending publisher) and add a GitHub publisher:

Owner: the owner of your linked repository
Repository name: the repository name
Workflow name: release-please.yml
Environment: leave blank (unless you set releaseEnvironment)

The automated publish runs as the publish job inside release-please.yml, so that is the workflow PyPI sees. If you also dispatch sdk-release.yml to re-publish a tag by hand, add it as a second publisher.

Keep the default config

{ "targets": { "python": { "publish": { "pypi": true } } } }

Publishing with a PyPI token#

Create a PyPI API token

On pypi.org, go to Account settings → API tokens → Add API token. Scope it to your project once the project exists.

Add it to the repository

Add the token as a repository secret named PYPI_API_TOKEN. See Adding repository secrets.

Switch the target to token auth

{
  "targets": {
    "python": {
      "publish": { "pypi": { "authMethod": "access-token" } }
    }
  }
}

The workflow uses pypa/gh-action-pypi-publish and passes PYPI_API_TOKEN as the upload password.

Notes#

skip-existing is enabled, so re-running a release for a version already on PyPI is a no-op.

Updated Sep 24, 2026