GitHub Actions: automatiza tests de Python

GitHub Actions permite ejecutar pruebas de Python automáticamente cada vez que alguien envía cambios al repositorio o abre un pull request. Este proceso forma parte de la integración continua: en lugar de depender de que cada desarrollador recuerde ejecutar los tests, el repositorio valida el código de manera repetible en un entorno limpio.

Qué necesitas antes de empezar

El proyecto debe estar en GitHub, tener una estructura clara y contar con pruebas automatizadas. Puedes utilizar pytest o unittest. La guía de pruebas unitarias en Python explica casos, fixtures, mocks y organización.

Qué es un workflow

Un workflow es un archivo YAML ubicado dentro de .github/workflows/. Define cuándo se ejecuta la automatización, qué máquina virtual utiliza y qué pasos debe realizar.

proyecto/
├── .github/
│   └── workflows/
│       └── tests.yml
├── src/
├── tests/
├── pyproject.toml
└── README.md

Primer workflow para Python

name: Tests de Python

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Descargar repositorio
        uses: actions/checkout@v4

      - name: Configurar Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Instalar dependencias
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Ejecutar tests
        run: pytest -q

Este archivo se ejecuta en cada push o pull request dirigido a main. La guía oficial de compilación y pruebas de Python con GitHub Actions presenta ejemplos actualizados.

Entender el bloque on

on define los eventos que activan el workflow. Puedes limitar ramas, rutas o tipos de evento:

on:
  pull_request:
    paths:
      - "src/**"
      - "tests/**"
      - "pyproject.toml"

Este filtro evita ejecutar pruebas cuando solo cambia documentación. Sin embargo, no filtres demasiado si un archivo aparentemente secundario puede afectar el resultado.

Jobs y steps

Un workflow contiene uno o más jobs. Cada job utiliza un runner y contiene pasos. Los jobs se ejecutan en paralelo por defecto, mientras que los pasos dentro de un job se ejecutan en orden.

La referencia oficial de sintaxis de workflows documenta eventos, jobs, permisos, matrices, condiciones y expresiones.

Instalar el propio paquete

Cuando el proyecto es un paquete, suele ser mejor instalarlo en modo editable:

- name: Instalar proyecto
  run: |
    python -m pip install --upgrade pip
    pip install -e .
    pip install pytest

Así las pruebas importan el paquete de una forma parecida a los usuarios. Si utilizas pyproject.toml, revisa también cómo gestionar dependencias con Poetry.

Probar varias versiones de Python

Una matriz ejecuta el mismo job en diferentes versiones:

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

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -e . pytest
      - run: pytest -q

fail-fast: false permite ver el resultado de todas las versiones aunque una falle.

Añadir caché de pip

setup-python puede guardar dependencias descargadas:

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
    cache: "pip"
    cache-dependency-path: requirements.txt

La caché reduce tiempo, pero no elimina la instalación. También debe invalidarse cuando cambian dependencias.

Variables de entorno

Las variables no sensibles pueden declararse con env:

env:
  APP_ENV: test
  LOG_LEVEL: warning

La guía de variables de entorno en Python explica cómo leerlas y validarlas.

Secretos

No escribas tokens, contraseñas o claves dentro del YAML. Guarda secretos en la configuración del repositorio y accede mediante ${{ secrets.NOMBRE }}. Evita imprimirlos y limita los permisos del workflow.

- name: Ejecutar prueba de integración
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}
  run: pytest tests/integration -q

En pull requests de forks, los secretos no se exponen normalmente. Diseña los tests para que las validaciones básicas funcionen sin credenciales.

Permisos mínimos

Configura únicamente los permisos necesarios:

permissions:
  contents: read

Un workflow de tests normalmente solo necesita leer el repositorio. Permisos amplios aumentan el impacto de una dependencia o acción comprometida.

Fijar versiones de acciones

Usar etiquetas mayores como @v4 es cómodo, pero proyectos con requisitos estrictos pueden fijar un commit completo. Revisa las acciones de terceros antes de incorporarlas y prefiere proveedores conocidos.

Linting y formato

Además de tests, puedes ejecutar herramientas de calidad:

- name: Revisar estilo
  run: |
    pip install ruff
    ruff check .
    ruff format --check .

Mantén pasos separados para saber qué falló. No mezcles instalación, lint, tests y build en un único comando difícil de diagnosticar.

Cobertura

Con pytest-cov puedes generar un informe:

- name: Tests con cobertura
  run: pytest --cov=src --cov-report=term-missing

La cobertura no garantiza calidad. Una línea ejecutada puede no estar bien verificada. Utiliza el indicador para encontrar áreas sin pruebas, no como objetivo aislado.

Servicios de base de datos

GitHub Actions puede iniciar PostgreSQL, Redis u otros servicios:

services:
  postgres:
    image: postgres:16
    env:
      POSTGRES_PASSWORD: postgres
    ports:
      - 5432:5432
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

Configura una base de prueba y nunca conectes el workflow a producción.

Artefactos

Cuando un test genera informes, puedes subirlos como artefactos. Esto ayuda a investigar fallos sin llenar el repositorio de archivos temporales.

Evitar duplicación

Si varios jobs repiten instalación, considera acciones compuestas o workflows reutilizables. Sin embargo, empieza con un archivo explícito. Una abstracción prematura puede dificultar entender el pipeline.

Depurar fallos

Lee primero el paso que falló, reproduce el comando localmente y verifica versiones. El entorno de CI es limpio y suele revelar dependencias no declaradas, rutas relativas incorrectas o tests que dependen del orden. La guía de funciones en Python y una buena separación del código facilitan crear pruebas aisladas.

Buenas prácticas

Mantén el workflow rápido, divide pruebas unitarias e integraciones, usa matrices solo para versiones soportadas, aplica caché con cuidado y limita permisos. Ejecuta las mismas herramientas localmente y en CI para evitar diferencias.

GitHub Actions transforma los tests en una condición automática para integrar cambios. Cuando cada pull request recibe una validación reproducible, los errores se detectan antes, las actualizaciones de dependencias son más seguras y el equipo puede refactorizar con mayor confianza.