Saltar al contenido

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. Un 3.10 sin comillas lo interpreta YAML como el número 3.1, un error clásico.
  • cache: pip almacena en caché la caché de descargas de pip, no el entorno virtual. La clave se construye a partir de los archivos indicados en cache-dependency-path. Si lo omite, setup-python solo busca requirements.txt. Consulte cómo almacenar en caché pip.
  • pip install ruff pytest está 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, concurrency y timeout-minutes son 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 -q mantiene los registros breves. Añada -x para 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.