Plantilla de flujo de trabajo de GitHub Actions para Python
Última actualización
Este es un .github/workflows/ci.yml funcional para un proyecto de Python. Almacena en caché las descargas de pip, prueba con tres versiones de Python, analiza el código con ruff y ejecuta pytest. Ajuste el paso de instalación si usa Poetry o uv.
El flujo de trabajo
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
concurrency:
group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
test:
runs-on: ubuntu-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
python: ["3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
cache: pip
cache-dependency-path: |
requirements*.txt
pyproject.toml
- run: python -m pip install --upgrade pip
- run: pip install -r requirements.txt -r requirements-dev.txt
- run: pip install ruff pytest
- run: ruff check .
- run: pytest -q
Qué hacen las partes menos evidentes
- Versiones entre comillas.
"3.11"debe ser una cadena. Un3.10sin comillas lo interpreta YAML como el número 3.1, un error clásico. cache: pipalmacena en caché la caché de descargas de pip, no el entorno virtual. La clave se construye a partir de los archivos indicados encache-dependency-path. Si lo omite,setup-pythonsolo buscarequirements.txt. Consulte cómo almacenar en caché pip.pip install ruff pytestestá aquí para que la plantilla funcione en un proyecto sin configurar. Si estas herramientas ya están en sus requisitos de desarrollo, elimine la línea.permissions,concurrencyytimeout-minutesson el mismo trío de seguridad que se usa en todas las plantillas: token de solo lectura, cancelación de las ejecuciones de pull request sustituidas y un límite de tiempo para el job.pytest -qmantiene los registros breves. Añada-xpara detenerse en el primer fallo mientras depura.
Variantes
Poetry
Instale Poetry con pipx install poetry, luego use cache: poetry en setup-python y poetry install --no-interaction. Ejecute los comandos con poetry run.
uv
Use astral-sh/setup-uv@v5 con enable-cache: true, después uv sync y uv run pytest.
Monorepo
Use working-directory: en los pasos, o defaults.run.working-directory en el job, y apunte cache-dependency-path al archivo de requisitos de cada paquete. Añada un filtro paths: para que solo se ejecuten los paquetes afectados.
Pruebas con base de datos
Añada un bloque services: con Postgres; la plantilla de Django muestra el patrón completo.
Job de despliegue
Añada un segundo job con needs: test y if: github.ref == 'refs/heads/main'. Construya la rueda con python -m build y súbala primero como artefacto.
macOS o Windows
Añada os: [ubuntu-latest, windows-latest] a la matriz si publica una biblioteca que debe funcionar en ambos sistemas.
Ejecútelo en máquinas más rápidas
Las suites de pruebas suelen ser la parte más lenta. Cambie una línea:
runs-on: [self-hosted, Linux, compiler-ci]
El job se ejecutará entonces en una máquina nueva de 8 vCPU de compiler.dev, con recurso automático a su runner original. Combínelo con pytest-xdist (pytest -n auto) para aprovechar los núcleos adicionales, y consulte por qué pytest es lento y precios.
Preguntas frecuentes
¿Debo almacenar en caché el virtualenv?
Normalmente no. Almacenar en caché las descargas de pip es más seguro. Un virtualenv en caché puede fallar cuando cambia la versión de parche de Python.
¿Cómo pruebo solo una versión de Python en los pull requests?
Use una matriz con todas las versiones en main y una sola versión en los pull requests, usando include. Consulte compilaciones con matriz.
¿Por qué tarda tanto pip install?
Los paquetes con extensiones compiladas se construyen desde el código fuente cuando no existe una rueda para su versión de Python. Fije versiones que incluyan ruedas.
¿Puedo acelerar pytest?
Sí: pytest-xdist para los núcleos, fragmentación de pruebas para las máquinas.
Relacionado
- Plantilla de flujo de trabajo de GitHub Actions para .NETCI de GitHub Actions para .NET listo para copiar: caché de NuGet, restauración, compilación, pruebas, servicio SQL Server, concurrencia y permisos.
- Plantilla de flujo de trabajo de GitHub Actions para DjangoCI de GitHub Actions para Django, listo para copiar y pegar: contenedor de servicio Postgres, caché de pip, comprobación de migraciones y tests.
- Plantilla de workflow de GitHub Actions para compilar DockerFlujo de trabajo de GitHub Actions para copiar y pegar: compile imágenes Docker con Buildx, capas en caché de GitHub y publique en GHCR desde main.
- Plantilla de flujo de trabajo de GitHub Actions para ElixirCI de GitHub Actions para Elixir y Phoenix, listo para copiar: servicio Postgres, caché de deps y _build con erlef/setup-beam, además de formato y pruebas.