PublishOnPyPI

Publish a wheel (*.whl) packages and/or source (*.tar.gz) package to PyPI.

Instantiation

Simple Example

The following example demonstrates how to publish the artifact named Package to PyPI on every pipeline run triggered by a Git tag. A secret is forwarded from GitHub secrets to a job secret.

jobs:
  # ...

  PublishOnPyPI:
    uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r8
    if: startsWith(github.ref, 'refs/tags')
    with:
      artifact: Package
    secrets:
      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

Complex Example

In this more complex example, the job depends on a parameter creation (Params) and packaging job (Package). The used Python version is overwritten by a parameter calculated in the Params jobs. Also the artifact name is managed by that job. Finally, the list of requirements is overwritten to load a list of requirements from dist/requirements.txt.

jobs:
  Params:
    # ...

  Package:
    # ...

  PublishOnPyPI:
    uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@r8
    if: startsWith(github.ref, 'refs/tags')
    needs:
      - Params
      - Package
    with:
      python_version: ${{ needs.Params.outputs.python_version }}
      requirements: -r dist/requirements.txt
      artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }}
    secrets:
      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image_version	no	string	`'26.04'`
python_version	no	string	`'3.14'`
requirements	no	string	`'wheel twine'`
artifact	yes	string	— — — —
dry_run	no	string	`'false'`
pypi_upload_url	no	string	`'https://upload.pypi.org/legacy/'`
cleanup	no	string	`'true'`

Goto secrets

Token Name	Required	Type	Default
PYPI_TOKEN	no	string	— — — —

Goto output parameters

This job template has no output parameters.

Input Parameters

ubuntu_image_version

Type:: string
Required:: no
Default Value:: '26.04'
Possible Values:: See actions/runner-images - Available Images for available Ubuntu image versions.
Description:: Version of the Ubuntu image used to run the job.

Note

Unfortunately, GitHub Actions has only a limited set of functions, thus, the usual Ubuntu image name like 'ubuntu-26.04' can’t be split into image name and image version.

python_version

Type:: string
Required:: no
Default Value:: '3.14'
Possible Values:: Any valid Python version conforming to the pattern <major>.<minor> or pypy-<major>.<minor>.
See actions/python-versions - available Python versions and actions/setup-python - configurable Python versions.
Description:: Python version used to run Python code in the job.

requirements

Type:: string
Required:: no
Default Value:: 'wheel twine'
Possible Values:: Any valid list of parameters for pip install.
Either a requirements file can be referenced using '-r path/to/requirements.txt', or a list of packages can be specified using a space separated list like 'wheel twine'.
Description:: Python dependencies to be installed through pip.

artifact

Type:: string
Required:: yes
Default Value:: — — — —
Possible Values:: Any valid artifact name.
Description:: Name of the artifact containing the packaged Python package(s).

dry_run

Type:: string
Required:: no
Default Value:: 'false'
Possible Values:: 'true' / 'false'
Description:: Validate the packages with twine check instead of uploading them to PyPI.
Everything up to the upload still runs, so the artifact download, the Python setup and the package metadata are exercised - only the two twine upload calls are skipped.
'true' - check the packages and publish nothing.
'false' - publish the packages.

pypi_upload_url

Type:: string
Required:: no
Default Value:: 'https://upload.pypi.org/legacy/'
Possible Values:: Upload URL of a package registry, as twine upload --repository-url takes it, e.g. 'https://test.pypi.org/legacy/' for TestPyPI.
Description:: The package registry the packages are uploaded to.
A registry’s upload URL isn’t its website: PyPI is https://pypi.org, but uploads go to https://upload.pypi.org/legacy/.

cleanup

Type:: string
Required:: no
Default Value:: 'true'
Possible Values:: 'true' / 'false'
Description:: Delete the artifact named by artifact after the packages were uploaded.
This job consumes the artifact, so a pipeline usually has no further use for it.
'true' - delete the package artifact.
'false' - keep it.

Secrets

PYPI_TOKEN

Type:: string
Required:: no
Default Value:: — — — —
Description:: The token to publish and upload packages on PyPI.

Outputs

This job template has no output parameters.

Optimizations

This template offers no optimizations (reduced job runtime).