How to Configure GitHub Actions CI for Python Using Poetry on Multiple Versions 🚀

Learn how to set up a robust GitHub Actions CI pipeline for your Python project using Poetry, testing across multiple Python versions to ensure compatibility and reliability.

Continuous Integration (CI) is a critical part of any modern software development workflow. If you’re managing dependencies and environments with Poetry, this guide will help you configure a robust GitHub Actions CI pipeline for your Python project across multiple Python versions. For a practical example, you can refer to the actual code in this GitHub repository: jdevto/python-poetry-hello. 🎉

Why Poetry for Python Projects? 🐍

Poetry simplifies Python dependency management and packaging. It provides:

• A clear pyproject.toml file for dependencies and project metadata.
• A virtual environment management system.
• Commands to build, publish, and manage dependencies.

Configuring GitHub Actions for Python Using Poetry on Multiple Versions

Below is a complete GitHub Actions workflow configuration to automate your CI pipeline with Poetry across Python versions 3.9 to 3.13. This example includes three types of triggers: on push to the main branch, on pull requests, and on a scheduled daily cron job. You can adjust these triggers to suit your own requirements.

name: ci

on:
  push:
    branches:
      - main
  pull_request:
  schedule:
    - cron: 0 12 * * *
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
      fail-fast: false

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Poetry
        run: |
          curl -sSL https://install.python-poetry.org | python3 -
          echo "PATH=$HOME/.local/bin:$PATH" >> $GITHUB_ENV

      - name: Install dependencies with Poetry
        run: |
          cd hello-world
          poetry install --with dev

      - name: Set PYTHONPATH to include the source directory
        run: echo "PYTHONPATH=$PWD/hello-world" >> $GITHUB_ENV

      - name: Run tests
        run: |
          cd hello-world
          poetry run pytest --cov=hello-world --cov-report=term-missing

Key Steps in the Workflow

1. Checkout Code

The actions/checkout@v4 action fetches your code from the repository so it can be used in subsequent steps.

2. Set Up Python

The actions/setup-python@v4 action installs the specified Python versions using a matrix strategy, enabling tests to run on multiple Python versions.

3. Install Poetry

The script installs the latest version of Poetry using its official installation method and ensures it’s added to the PATH.

4. Install Dependencies

poetry install --with dev installs all the project’s dependencies, including development dependencies.

5. Set PYTHONPATH

The PYTHONPATH environment variable is configured to include the src directory, enabling proper module imports during testing.

6. Run Tests

poetry run pytest runs the tests defined in your project, with coverage reporting enabled via --cov=src --cov-report=term-missing.

Enhancements

1. Add Caching for Dependencies

To speed up your workflow, you can cache Poetry dependencies:

      - name: Cache Poetry dependencies
        uses: actions/cache@v4
        with:
          path: ~/.cache/pypoetry
          key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
          restore-keys: |
            ${{ runner.os }}-poetry-

Add this step before installing dependencies to skip re-installing dependencies if nothing has changed.

Conclusion

By configuring this GitHub Actions workflow, you can automate testing across multiple Python versions and ensure that your Python project using Poetry is always in top shape. This setup includes steps to install dependencies, run tests, and even cache dependencies for faster builds. 🚀

If you have any questions or suggestions, feel free to share! 🙌 For more inspiration and a working example, visit the GitHub repository: jdevto/python-poetry-hello.