Introduction

This article will guide you through setting up a GitHub workflow that automatically updates your PYPI package upon a new GitHub release, using my zomboid_rcon repository as a practical example.

Understanding the Workflow

The process involves a GitHub workflow specifically designed to upload a Python package to PYPI when a new release is published. This method not only simplifies the release process but also ensures that the latest version of your package is always available for users.

Preparing Your Package

pyproject.toml

Before diving into the GitHub Actions workflow, ensure your package is properly configured. This involves setting up your pyproject.toml file with all necessary package information, including name, version, description, license, and dependencies.

You can see an example of this file in my zomboid_rcon project.

[build-system]
requires      = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "zomboid_rcon"
version = "1.0.2"
description = "Python class for interacting with Project Zomboid servers using RCON "
readme = "README.md"
license = { file = "LICENSE" }
authors = [{ name = "Jack Whitworth", email = "[email protected]" }]
classifiers = [
    'Development Status :: 5 - Production/Stable',
    'Intended Audience :: Developers',
    'Topic :: Software Development :: Build Tools',
    'License :: OSI Approved :: GNU General Public License (GPL)',
    'Programming Language :: Python :: 3.8',
    'Programming Language :: Python :: 3.9',
    'Programming Language :: Python :: 3.10',
    'Programming Language :: Python :: 3.11',
]
keywords = [
    'project-zomboid',
    'rcon',
    'project-zomboid-rcon'
]
dependencies = [
    "rcon >= 2.3.9",
    "timeout_decorator >= 0.5.0"
]
requires-python = ">=3.8"

[project.optional-dependencies]
dev = []

[project.urls]
Homepage = "https://github.com/JMWhitworth/zomboid_rcon"

python-publish.yml

This is detailed in the ‘Setting Up Github Actions’ section next, but you will be required to create a python-publish.yml file. You can see an example of this file in my zomboid_rcon project. This is located under .github/workflows/python-publish.yml.

name: Upload Python Package

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  deploy:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v3
      with:
        python-version: '3.x'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build
    - name: Build package
      run: python -m build
    - name: Publish package
      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
      with:
        user: __token__
        password: ${{ secrets.PYPI_API_TOKEN }}

Setting Up GitHub Actions

  1. Create a Workflow File: Start by creating a .github/workflows directory in your repository, and add a YAML file for the workflow, for instance, publish-to-pypi.yml.
  2. Define Workflow Triggers: Configure the workflow to trigger on a new release using the on: release: types: [published] event.
  3. Setup the Job: Define the steps necessary to publish your package, including checking out the repository, setting up Python, installing dependencies, building your package, and finally, publishing to PYPI using Twine.
  4. Secure PYPI API Token: Utilize GitHub secrets to securely store your PYPI API token, referenced in the workflow as ${{ secrets.PYPI_API_TOKEN }}, to authenticate the package upload.
  5. Finalize and Test: With the workflow defined, commit your changes and create a new release to test the automation. If configured correctly, your package should be automatically published to PYPI.

Here is a screenshot showing PYPI_API_TOKEN set as a Repository secret:

A screenshot of the Secrets and variables options within GitHub

This automated process not only streamlines the update and release cycle for Python packages but also encourages best practices in software development and distribution. By integrating such workflows, developers can focus more on development and less on the nuances of package deployment.

Conclusion

Automating your PYPI updates with GitHub Actions represents a significant leap towards efficient software distribution. By following the steps outlined, leveraging the example of the zomboid_rcon package, developers can ensure their projects remain up-to-date on PYPI, facilitating easy access and installation by the end-users. Embrace automation, and make your development workflow more productive and error-free.

For a more detailed look into automating PYPI updates with GitHub Actions, exploring the zomboid_rcon GitHub repository and its workflow configuration can provide valuable insights and a practical example to guide you through the process.