Mantener idénticas las comprobaciones locales y las de CI: un único punto de entrada, herramientas fijadas, el mismo contenedor

Objetivo

Una comprobación que pasa localmente pasa en CI y viceversa, de modo que desaparezcan los commits de «arreglar lint», los fallos exclusivos de CI y las disputas de «aquí funciona», y un agente pueda confiar en su ejecución local como predicción del pipeline.

Requisitos previos

Un punto de entrada de ejecutor de tareas para cada comprobación (véase el artículo relacionado), un manifiesto de versiones para la cadena de herramientas, y un servicio de CI que pueda ejecutar una imagen de contenedor a elección. GitHub Actions documenta la ejecución de los pasos de un job dentro de un contenedor declarado con container: y una image:; asdf lee las versiones de las herramientas desde un archivo .tool-versions e instala todo lo listado con asdf install; mise lee el mismo archivo o un mise.toml con una sección [tools].

Pasos

1. Definir cada comprobación una sola vez como una tarea con nombre (lint, typecheck, test, build) y hacer que el flujo de trabajo de CI llame solo a esos nombres. Donde CI necesite un comportamiento distinto (sin modo watch, salida legible por máquina), añadir un indicador que la tarea acepte en lugar de un segundo comando.
2. Fijar la cadena de herramientas en un manifiesto versionado en el repositorio (.tool-versions, mise.toml, o el Dockerfile del contenedor de desarrollo), y hacer que tanto el arranque local como el job de CI instalen a partir de él; nunca latest.
3. Ejecutar CI dentro de la misma imagen de contenedor que usa el entorno de desarrollo, o construir la imagen en CI a partir del mismo Dockerfile, para que también coincidan los paquetes del sistema operativo.
4. Fijar en el archivo de bloqueo del proyecto las herramientas que realizan las comprobaciones (formateador, linter, ejecutor de pruebas), en lugar de como instalaciones globales, e invocarlas a través de la tarea para que la versión bloqueada sea la única que pueda ejecutarse.
5. Eliminar las diferencias de entorno: evitar rutas de código que se comporten de forma distinta cuando hay una variable CI definida, fijar la configuración regional y la zona horaria dentro de la tarea (LC_ALL=C.UTF-8, TZ=UTC), y hacer que las cachés sean entradas opcionales, no requisitos.
6. Añadir un job programado que ejecute el conjunto completo de comprobaciones desde un clon limpio en el contenedor, sin ninguna caché; detecta las comprobaciones que pasan localmente solo por estado residual.
7. Cuando CI falle y lo local pase, tratar la diferencia como el defecto: registrar la discrepancia (versión, variable de entorno, archivo faltante) y eliminarla antes de corregir el síntoma.

Resultado esperado

El archivo de flujo de trabajo es corto: comprobar el código, instalar desde el manifiesto, ejecutar las tareas con nombre. Cualquier colaborador reproduce un fallo de CI con el mismo nombre de comando, y el tiempo de CI se dedica a las comprobaciones y no a la desviación de configuración.

Límites y base de verificación

El comportamiento dependiente del hardware (número de CPU, límites de memoria, GPU) sigue siendo distinto y se manifiesta en pruebas sensibles a los tiempos. Los secretos y las credenciales de servicio difieren por diseño; las comprobaciones que los necesitan quedan fuera del conjunto de paridad. Este es un procedimiento propuesto basado en la documentación citada; no se afirma ninguna cifra de tasa de defectos.

Ejecutar las comprobaciones en modo CI en ambos lados

Muchas herramientas ya cambian de comportamiento cuando la variable de entorno CI está definida: los ejecutores de pruebas dejan de escribir snapshots nuevos y desactivan el modo watch, los gestores de paquetes se niegan a modificar el archivo de bloqueo, y las configuraciones de prueba generadas por scaffolding prohíben las pruebas enfocadas. Esas ramas no pueden eliminarse, así que la regla de paridad es la inversa de evitarlas: la tarea que ejecuta el conjunto de comprobaciones exporta ella misma CI=true, de modo que la ejecución local y el pipeline tomen las mismas ramas en cada herramienta de terceros. El propio código del proyecto no debería ramificarse en función de CI en absoluto. Una comprobación que pasa sin la variable y falla con ella es entonces reproducible localmente con el mismo comando.