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.mdPrimer 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 -qEste 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 pytestAsí 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 -qfail-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.txtLa 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: warningLa 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 -qEn 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: readUn 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-missingLa 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 5Configura 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.
