build-and-publish-package-to-pypi.yml

# GitHub Actions workflow that builds and publishes a Python package to PyPI.
name: Build and publish package to PyPI

on:
  release:
    types: [ published ]

# Note: Since the building and publishing are done in separate jobs,
#       we use GitHub's artifact persistent system to give the later
#       job access to files generated by the earlier job.
jobs:
  build:
    name: Build package
    runs-on: ubuntu-latest
    steps:
      - name: Check out commit  # Docs: https://github.com/actions/checkout
        uses: actions/checkout@v4
      - name: Set up Python  # Docs: https://github.com/actions/setup-python
        uses: actions/setup-python@v5
        with:
          # Specify a Python version that satisfies the `tool.poetry.dependencies.python`
          # version requirement specified in `pyproject.toml`.
          python-version: '3.10'
      - name: Install Poetry  # Docs: https://github.com/snok/install-poetry
        uses: snok/install-poetry@v1
      - name: Install dependencies  # Docs: https://python-poetry.org/docs/cli/#install
        run: poetry install --no-interaction
      - name: Run tests  # TODO: Consider extracting this and preceding steps into a separate job and/or workflow
        run: poetry run pytest -v
      - name: Update package version  # Docs: https://python-poetry.org/docs/cli/#version
        run: poetry version ${{ github.ref_name }}
      - name: Build package  # Docs: https://python-poetry.org/docs/cli/#build
        run: poetry build
      - name: Save the built package for publishing later  # Docs: https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@v4
        with:
          name: built-package
          path: dist
          if-no-files-found: error
          retention-days: 1  # Note: 1 day is the shortest period possible

  # Note: This job is separate from the others so that this job's permissions are not
  #       unnecessarily granted to the other jobs.
  publish:
    name: Publish package
    needs: [ build ]
    runs-on: ubuntu-latest
    environment:
      name: pypi
      url: https://pypi.org/p/refscan
    permissions:
      # Note: According to the documentation of the `pypa/gh-action-pypi-publish` Action,
      #       the `id-token: write` permission is mandatory for trusted publishing to PyPI.
      #       Reference: https://github.com/pypa/gh-action-pypi-publish
      #       Reference: https://docs.pypi.org/trusted-publishers/
      id-token: write
    steps:
      - name: Load the built package for publishing  # Docs: https://github.com/actions/download-artifact
        uses: actions/download-artifact@v4
        with:
          name: built-package
          path: dist
      - name: List contents of `dist` directory
        run: ls -lh dist
      - name: Publish package to PyPI  # Docs: https://github.com/pypa/gh-action-pypi-publish
        uses: pypa/gh-action-pypi-publish@release/v1