Linting en CI/CD
Las puertas de linting en CI/CD bloquean las fusiones cuando el código viola las reglas de estilo, tipo o seguridad. Cada pull request recibe las mismas comprobaciones independientemente de la configuración del editor local.
Receta
# .github/workflows/lint.yml
name: lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
- run: uv sync --frozen --group dev
- run: uv run ruff check .
- run: uv run ruff format --check .
- run: uv run mypy src/Cuándo usar esto:
- Los desarrolladores omiten los hooks de pre-commit
- La revisión de código detecta el formato en lugar de la lógica
- Necesitas evidencia de auditoría de las puertas de calidad
Ejemplo de Trabajo
name: quality
on:
pull_request:
branches: [main]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
Lo que esto demuestra:
uv sync --frozenasegura la integridad del archivo de bloqueo- Pasos de verificación y formato separados para mensajes de error claros
- mypy se ejecuta solo en
src/(no en tests) - El trabajo opcional de pre-commit detecta a los desarrolladores que omiten los hooks
Inmersión Profunda
Pipeline de Linting en CI
| Paso | Comando | Falla en |
|---|---|---|
| Lint | ruff check . | Estilo, bugs, seguridad |
| Formato | ruff format --check . | Código sin formato |
| Tipos | mypy src/ | Errores de tipo |
| Hooks | pre-commit run --all-files | Cualquier fallo de hook |
Consejos de Rendimiento
- Caché de
.venvcon clave basada en el hash del archivo de bloqueo - Caché de
.ruff_cachey.mypy_cache - Ejecutar trabajos de linting y pruebas en paralelo
Trampas Comunes
- Sin
--checken el formateador - La CI aplica automáticamente el formato. Solución:ruff format --checkfalla en lugar de arreglar. - La CI instala la última versión de ruff - diferente de la local. Solución: bloquear las dependencias de desarrollo en
uv.lock; usar--frozen. - mypy sin dependencias del proyecto - errores de importación. Solución:
uv sync --group devantes de mypy. - Linting de
migrations/- fallos ruidosos en código generado. Solución: excluir en la configuración de ruff. - Comprobaciones requeridas no aplicadas - los PRs se fusionan a pesar de los fallos. Solución: reglas de protección de ramas que requieren el trabajo de linting.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Pre-commit.ci | Runner de hooks gestionado | Se requiere CI auto-alojada |
| Reviewdog | Anotaciones de PR en línea | Es suficiente un simple pasar/fallar |
| SonarQube | Cumplimiento empresarial | Proyectos pequeños |
Preguntas Frecuentes
¿Deben el linting y las pruebas ser un solo trabajo?
Trabajos separados se ejecutan en paralelo y dan mensajes de error más claros.
¿Cómo hago caché de uv en GitHub Actions?
setup-uv maneja la caché. Clave en el hash de uv.lock.
¿Debería la CI arreglar automáticamente el formato?
No. Falla y deja que el desarrollador lo arregle localmente. La corrección automática en CI oculta el problema.
¿Cómo hago linting solo de los archivos modificados?
Usa ruff check $(git diff --name-only origin/main) para velocidad en repositorios grandes.
¿Qué pasa con GitLab CI?
Los mismos comandos en un bloque script: después de instalar uv.
¿Debería la rama main ejecutar linting también?
Sí, en push a main como una red de seguridad. Las comprobaciones de PR son la puerta principal.
¿Cómo añado una puerta de cobertura?
pytest --cov-fail-under=80 en el trabajo de pruebas junto con el linting.
¿Puedo omitir el linting para PRs solo de documentación?
Usa filtros de ruta: paths-ignore: ['**.md'] en el disparador del workflow.
¿Cómo reporto los resultados de linting en comentarios de PR?
Herramientas como reviewdog o los localizadores de problemas de GitHub Actions anotan la diferencia.
¿Qué pasa si el linting tarda demasiado?
Limita mypy a src/, usa caché agresivamente, haz linting solo de los archivos modificados en repositorios grandes.
Relacionado
- Configuración de Ruff - configuración de ruff
- Hooks de pre-commit - hooks locales
- mypy y pyright en CI - verificación de tipos
- Mejores Prácticas de Linting y Formateo - política
Versiones de la pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.