Automate Python Tests with GitHub Actions in 5 Minutes

Leandro Hirt

Atualizado em: 29/05/2026

Published on: May 29, 2026

Reading time: 6 minutes

Have you ever felt nervous pushing code to production without knowing whether it actually works? The good news is that you can eliminate that worry for good. Automating Python tests with GitHub Actions is the fastest and most efficient way to ensure every change in your project is validated automatically. By integrating Continuous Integration (CI) directly into your repository, you transform a manual workflow into a professional, reliable production pipeline.

GitHub Actions is an automation tool built into GitHub that runs scripts whenever an event occurs, such as a push or a pull request. For anyone who already uses Python unit tests, setting up this automation is the logical next step for scaling software quality. If you want to stop running everything manually in the terminal, this tutorial shows you how to set it all up in just 5 minutes using modern industry standards.

What is GitHub Actions and why use it with Python?

GitHub Actions is a continuous integration and delivery (CI/CD) service. Think of it as a robot that lives inside your repository. Every time you push new code, that robot spins up a temporary virtual machine, installs Python, downloads your dependencies, and runs the commands you defined. If something goes wrong, it notifies you immediately by email or with a red icon next to your commit.

This eliminates the classic “it works on my machine” problem. Because the tests run in a clean, isolated environment, you can be sure the code is portable. This practice is a standard required by major tech companies, as documented in references on Continuous Integration.

Preparing the local environment

Before configuring the GitHub robot, make sure your Python code has valid tests and a clean dependency file. GitHub Actions needs to know which libraries to install to run your script — typically a requirements.txt file lists them.

If you are just getting started, it is essential that your project be organized inside a Python virtual environment. This captures the exact library versions you are using without polluting the global operating system. Without an isolated environment, you may face a ModuleNotFoundError when GitHub tries to run your code and cannot find the necessary tools.

Creating the unit tests

Create a folder called tests and a file called test_calculations.py inside it. The pytest library is used here — the industry standard for its simplicity and power. The goal is to have something GitHub Actions can run and verify as either “pass” or “fail”.

# Simple test example to validate the automation
def add(a, b):
    return a + b

def test_add_positive():
    assert add(2, 3) == 5

def test_add_negative():
    assert add(-1, -1) == -2

Configuring the GitHub Actions workflow

To automate Python tests with GitHub Actions, a YAML configuration file needs to be created. This file must be placed inside a specific folder in your repository called .github/workflows/. The filename can be anything, such as main.yml or tests.yml.

This YAML file contains the “recipes” for how the GitHub server should behave. It defines the operating system (e.g. Ubuntu), the Python version, and the terminal commands. Proper indentation is critical in YAML — a single wrong space can prevent the script from running.

Basic .yml file structure

name: Python CI Tests

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

Installing dependencies

Next, add a step to read your requirements.txt. If you use modern tooling, you can also manage dependencies with Poetry, but for this 5-minute guide, traditional pip is the most direct path.

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install pytest
    if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

Running the tests

The final part of the automation is the command that actually runs the tests. If pytest finds any errors in your code, it returns a failure code to the GitHub runner, marking the automation as unsuccessful — exactly as described in the official GitHub Actions documentation.

- name: Test with pytest
  run: |
    pytest

Complete workflow file

Below is the complete content to place inside .github/workflows/python-app.yml in your repository. Make sure your main Python code and your tests folder are at the project root so the runner can locate them.

# Workflow name
name: Python Tests CI

# Events that trigger the automation
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  python_tests:
    # Operating system choice
    runs-on: ubuntu-latest

    steps:
    # Step 1: Download the repository code to the runner
    - uses: actions/checkout@v3

    # Step 2: Configure the desired Python version
    - name: Set up Python 3.10
      uses: actions/setup-python@v4
      with:
        python-version: "3.10"

    # Step 3: Install dependencies
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install pytest
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

    # Step 4: Run the test suite
    - name: Run tests with Pytest
      run: |
        pytest

Advanced tips for faster workflows

As your project grows, you can optimize the Actions run time. A common technique is using GitHub’s caching system so libraries do not need to be downloaded from scratch on every run. Another important practice is running tests against multiple Python versions simultaneously with a Matrix Build, which ensures that users on Python 3.8 have the same experience as those on 3.12. This level of care is what separates amateur projects from professional packages that consider all Python data types and their compatibility.

Automation does not just find bugs — it gives developers the confidence to innovate fast.

Handling test failures

When a test fails in GitHub Actions, the console logs show exactly where the assertion went wrong. Often the cause is a simple syntax error that slipped past the local editor, or a file path issue. Developers accustomed to Windows may forget that GitHub runs on Linux, where directory slashes differ, which can trigger a FileNotFoundError during automation.

Next steps

Automating Python tests with GitHub Actions is a turning point in any programmer’s career. Now that the Continuous Integration foundation is working, you can explore how to create an installable pip package and integrate the package build directly into Actions, automating publication to PyPI every time you create a new version.