This action allows you to upload your Python distribution packages in the dist/ directory to PyPI. This text suggests a minimalistic usage overview. For more detailed walkthrough check out the PyPA guide.

If you have any feedback regarding specific action versions, please leave comments in the corresponding per-release announcement discussions.

The master branch version has been sunset. Please, change the GitHub Action version you use from master to release/v1 or use an exact tag, or opt-in to use a full Git commit SHA and Dependabot.

This example jumps right into the current best practice. If you want to use API tokens directly or a less secure username and password, check out how to specify username and password.

This action supports PyPI's trusted publishing implementation, which allows authentication to PyPI without a manually configured API token or username/password combination. To perform trusted publishing with this action, your project's publisher must already be configured on PyPI.

To enter the trusted publishing flow, configure this action's job with the id-token: write permission and without an explicit username or password:

# .github/workflows/ci-cd.yml
jobs:
  pypi-publish:
    name: Upload release to PyPI
    runs-on: ubuntu-latest
    environment:
      name: pypi
      url: https://pypi.org/p/<your-pypi-project-name>
    permissions:
      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
    steps:
    # retrieve your distributions here

    - name: Publish package distributions to PyPI
      uses: pypa/gh-action-pypi-publish@release/v1

Other indices that support trusted publishing can also be used, like TestPyPI:

- name: Publish package distributions to TestPyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    repository-url: https://test.pypi.org/legacy/

(don't forget to update the environment name to testpypi or similar!)

A common use case is to upload packages only on a tagged commit, to do so add a filter to the job:

    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')

Generating signed digital attestations for all the distribution files and uploading them all together is now on by default for all projects using Trusted Publishing. To disable it, set attestations as follows:

   with:
     attestations: false

The attestation objects are created using Sigstore for each distribution package, signing them with the identity provided by the GitHub's OIDC token associated with the current workflow. This means both the trusted publishing authentication and the attestations are tied to the same identity.

This GitHub Action has nothing to do with building package distributions. Users are responsible for preparing dists for upload by putting them into the dist/ folder prior to running this Action. They are typically expected to do this in a separate GitHub Actions CI/CD job running before the one where they call this action and having restricted privileges.

The expected environment for running pypi-publish is the GitHub-provided Ubuntu VM. We are running a smoke-test against ubuntu-latest in CI but any currently available numbered versions should do. We'll consider them supported for as long as GitHub itself supports them.

Running the action in a job that has a container: set is not supported. It might work for you but you're on your own when it breaks. If you feel the need to use it, it's likely that you're not following the recommendation of invoking the build automation in a separate job, which is considered a security issue (especially, when using Trusted Publishing that may cause privilege escalation and would enable the attackers to impersonate the GitHub-backed identity of the repository through transitive build dependency poisoning). The solution is to have one job (or multiple, in case of projects with C-extensions) for building the distribution packages, followed by another that publishes them.

Self-hosted runners are best effort, provided no other unsupported things influence them. We are unable to test this in CI and they may break. This is often the case when using custom runtimes and not the official GitHub-provided VMs. In general, if you follow the recommendation of building in a separate job, you shouldn't need to run this action within a self-hosted runner — it should be possible to build your dists in a self-hosted runner, save them as a GitHub Actions artifact in that job, and then invoke the publishing job that would run within GitHub-provided runners, downloading the artifact with the dists and publishing them. Such separation is the recommended/supported way of handling this scenario. Our understandng is that Trusted publishing is expected to work on self-hosted runners. It is backed by OIDC. If it doesn't work, you should probably ask GitHub if you missed something. We wouldn't be able to assist here.

Trusted Publishing cannot be tested in CI at the moment, sadly. It is supported and bugs should be reported but it may take time to sort out as it often requires cross-project collaboration to debug (sometimes, problems occur due to changes in PyPI and not in the action).

The only case that is explicitly unsupported at the moment is Trusted Publishing in reusable workflows. This requires support on the PyPI side and is being worked on. Please, do not report bugs related to this case. The current recommendation is to put everything else you want into a reusable workflow but keep the job calling pypi-publish in a top-level one.

Invoking pypi-publish from composite actions is unsupported. It is not tested. GitHub Runners have limitations and bugs in this case. But more importantly, this is usually an indication of using it insecurely. When using Trusted Publishing, it is imperative to keep build machinery invocation in a separate job with restrictive privileges as Trusted Publishing itself requires elevated permissions to make use of OIDC. Our observation is that the users sometimes create in-project composite actions that invoke building and publishing in the same job. As such, we don't seek to support such a dangerous configuration in the first place. The solution is pretty much the same as with the previous problem — use a separate job with dedicated and scoped privileges just for publishing; and invoke that in-project composite action from a different job.

And finally, invoking pypi-publish more than once in the same job is not considered supported. It may work in a limited number of scenarios but please, don't do this. If you want to publish to several indexes, build the dists in one job and add several publishing jobs, one per upload.

For best results, figure out what kind of workflow fits your project's specific needs.

For example, you could implement a parallel job that pushes every commit to TestPyPI or your own index server, like devpi. For this, you'd need to (1) specify a custom repository-url value and (2) generate a unique version number for each upload so that they'd not create a conflict. The latter is possible if you use setuptools_scm package but you could also invent your own solution based on the distance to the latest tagged commit.

You'll need to create another token for a separate host and then save it as a GitHub repo secret under an environment used in your job. Though, passing a password would disable the secretless trusted publishing so it's better to configure it instead, when publishing to TestPyPI and not something custom.

The action invocation in this case would look like:

- name: Publish package to TestPyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    password: ${{ secrets.TEST_PYPI_API_TOKEN }}
    repository-url: https://test.pypi.org/legacy/

You can change the default target directory of dist/ to any directory of your liking. The action invocation would now look like:

- name: Publish package to PyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    packages-dir: custom-dir/

It is recommended that you run twine check just after producing your files, but this also runs twine check before upload. You can also disable the twine check with:

   with:
     verify-metadata: false

Sometimes, when you publish releases from multiple places, your workflow may hit race conditions. For example, when publishing from multiple CIs or even having workflows with the same steps triggered within GitHub Actions CI/CD for different events concerning the same high-level act.

To facilitate this use-case, you may use skip-existing (disabled by default) setting as follows:

   with:
     skip-existing: true

Sometimes, twine upload can fail and to debug use the verbose setting as follows:

   with:
     verbose: true

You may want to verify whether the files on PyPI were automatically uploaded by CI script. It will show SHA256, MD5, BLAKE2-256 values of files to be uploaded.

  with:
    print-hash: true

The default username value is __token__. If you publish to a custom registry that does not provide API tokens, like devpi, you may need to specify a custom username and password pair. This is how it's done.

  with:
    user: guido
    password: ${{ secrets.DEVPI_PASSWORD }}

The secret used in ${{ secrets.DEVPI_PASSWORD }} needs to be created on the environment page under the settings of your project on GitHub. See Creating & using secrets.

In the past, when publishing to PyPI, the most secure way of the access scoping for automatic publishing was to use the API tokens feature of PyPI. One would make it project-scoped and save as an environment-bound secret in their GitHub repository settings, naming it ${{ secrets.PYPI_API_TOKEN }}, for example. See Creating & using secrets. While still secure, trusted publishing is now encouraged over API tokens as a best practice on supported platforms (like GitHub).

The Dockerfile and associated scripts and documentation in this project are released under the BSD 3-clause license.