Configuración de integración continua
Decide qué se ejecuta al hacer push y en cada solicitud de cambio, y luego escríbelo en la sintaxis que entienda la forja del proyecto. Las decisiones en este archivo son independientes de la forja: detecta el ecosistema, decide qué debe ejecutarse, elige una matriz, decide el caché. La sintaxis que expresa esas decisiones no lo es, por lo que reside en references/github-actions.md para GitHub Actions y en references/gitlab.md para GitLab CI/CD. Lee el archivo de referencia correspondiente antes de escribir cualquier configuración; no escribas la sintaxis de una forja traduciendo las palabras clave de la otra, porque las dos tienen formas diferentes para los disparadores, las matrices y el caché.
Alcance
Esta habilidad posee lo que se ejecuta: qué verificaciones se realizan, en qué disparadores, en qué versiones, con qué caché. Comparte los archivos de flujo de trabajo y de pipeline que escribe con otras dos habilidades, y el límite entre ellas es el área de reglas, no una descripción de archivos.
Las reglas de CI a continuación (R-CI-*) pertenecen aquí. Las reglas SEC, la postura de seguridad de los mismos archivos, como pines de SHA de acciones, permisos mínimos, actualizadores de dependencias, protección de ramas e imágenes fijas, pertenecen a oss-harden. Las reglas REL, publicar un artefacto construido en un registro con publicación confiable, procedencia y una puerta de aprobación, pertenecen a oss-publish. No agregues un bloque permissions:, fijes un SHA, configures protección de ramas ni escribas un trabajo de publicación mientras trabajes desde esta habilidad; anota que el proyecto lo necesita y pasa el trabajo a la habilidad que lo posee.
Desplegar un sitio estático construido en el alojamiento de Pages de la propia forja también es algo que se ejecuta al hacer push, por lo que se queda aquí en lugar de con oss-publish, que posee los lanzamientos de registros. Ninguna regla lo requiere: un proyecto publica un sitio porque tiene uno, por lo que se escribe solo cuando el repositorio construye un sitio y el usuario solicita el despliegue.
Principios
Verifica todo antes de agregar un paso, un secreto o un valor de configuración: lee el repositorio real en lugar de adivinar su forma. Pregunta cuando algo sea incierto en lugar de inventar una respuesta plausible.
Llama a la automatización del propio proyecto en lugar de escribir lógica de shell dentro del pipeline. Un paso que ejecuta npm test en lugar de jest --coverage --ci mantiene el pipeline y el portátil de un colaborador ejecutando el mismo comando, que es lo que verifica R-CI-02. Cuando no exista tal automatización, pregunta si agregarla al proyecto o recurrir a comandos en línea.
Presenta opciones de política en lugar de adivinarlas, incluso cuando el repositorio ya contenga pruebas, un Dockerfile o un pipeline. Qué se ejecuta en una solicitud de cambio, qué dispara una compilación de lanzamiento y cómo ocurre el despliegue son decisiones que toma el usuario; el código solo te dice qué es posible, no qué se desea.
Proceso
Paso 1: Detectar la forja
Busca un directorio .github/workflows/ existente o un archivo .gitlab-ci.yml, verifica el remoto git para un host github.com o gitlab, o pregunta directamente si ninguna señal está presente. Esto decide qué archivo de referencia rige los Pasos 6 y 7. Si el usuario indica la forja explícitamente, confía en eso por encima de cualquier señal encontrada en el repositorio.
Paso 2: Analizar el repositorio
Identifica el lenguaje y el runtime a partir de los archivos fuente y el manifiesto del paquete, y anota el rango de versiones que el proyecto afirma soportar; la matriz en el Paso 4 debe cubrirlo todo, incluida la versión más antigua y la más nueva soportada, según R-CI-03.
Encuentra cada comando aplicable de lint, prueba, typecheck y compilación que el proyecto ya defina, ya sean scripts del gestor de paquetes, un Makefile, un Rakefile o una herramienta como tox o just, y léelos con suficiente detalle para conocer sus argumentos y efectos secundarios. No inventes una clase de verificación faltante: un repositorio de documentación puede no tener compilación, y un script pequeño puede no tener linter. Si el repositorio tiene una guía CONTRIBUTING, sus comandos y la automatización del proyecto deben coincidir; resuelve cualquier conflicto antes de copiar cualquiera de ellos en CI.
Lee cualquier configuración de CI existente antes de cambiarla, para saber si debes extenderla o reemplazarla.
Identifica cada archivo de bloqueo que el proyecto confirma, como package-lock.json, Gemfile.lock, poetry.lock o Cargo.lock, y qué caché de descarga del gestor de paquetes puede reutilizar cada comando de instalación de forma segura. No asumas que un directorio de dependencias instaladas es un caché.
Encuentra .env.example y busca en el código fuente las variables de entorno requeridas, para que un paso que necesite un secreto se identifique antes de la generación en lugar de después de una ejecución fallida.
Paso 3: Presentar hallazgos y preguntar
Resume lo que encontró el Paso 2, luego pregunta sobre las elecciones que el código solo no puede responder: qué debería ejecutarse en una solicitud de pull o merge, qué debería disparar una compilación de lanzamiento y si la CI existente debe extenderse o reemplazarse. Pregunta solo lo que aplica a este proyecto; un proyecto sin Dockerfile no recibe preguntas sobre un registro.
Donde el Paso 2 encontró una compilación que produce un sitio estático, pregunta si también debe desplegarse y a dónde. Un sitio puede construirse como una verificación y nunca publicarse, por lo que trata una compilación estática como una pregunta en lugar de como un consentimiento para desplegar uno.
Paso 4: Elegir la matriz
Construye la matriz de versiones a partir de las líneas de lanzamiento compatibles identificadas en el Paso 2, no de una única versión fija. Incluye cada línea de lanzamiento mayor o menor mantenida que el proyecto afirme soportar. Un proyecto sin rango de soporte declarado obtiene un pipeline de una sola versión en lugar de una matriz inventada; no fabriques afirmaciones de soporte que el manifiesto no haga. Si un rango es continuo e incluye líneas de lanzamiento que el proyecto no tiene intención de soportar, corrige el rango declarado en lugar de probar silenciosamente un subconjunto.
Paso 5: Decidir el caché
Caché solo los datos de descarga del gestor de paquetes u otro directorio que la documentación oficial de la herramienta indique que es seguro reutilizar. Prefiere la acción oficial de configuración de runtime de la forja cuando soporte el gestor de paquetes detectado y genere un hash del archivo de bloqueo. De lo contrario, clave un caché explícito en el archivo de bloqueo más cada límite de compatibilidad que cambie su contenido, como el sistema operativo, la arquitectura, el runtime y el gestor de paquetes. Una clave de respaldo es opcional y no debe cruzar uno de esos límites. Un proyecto sin archivo de bloqueo o sin caché de descarga reutilizable no obtiene un paso de caché.
Paso 6: Escribir la configuración
Abre el archivo de referencia para la forja elegida en el Paso 1 y sigue su sintaxis exactamente. Ambos archivos de referencia cubren la activación al hacer push a la rama predeterminada y en cada solicitud de cambio (R-CI-01), un tiempo de espera en cada trabajo con cancelación de ejecuciones reemplazadas en la misma rama (R-CI-05) y las decisiones de caché del Paso 5 (R-CI-04). Ambos también llevan una sección de despliegue de Pages, utilizada solo cuando el Paso 3 estableció que el proyecto quiere una. Ningún archivo de referencia cubre permisos, fijación de SHA o publicación; esos permanecen fuera del archivo que escribes aquí.
Paso 7: Validar antes de presentar
Confirma que la configuración sea sintácticamente válida con el validador de la propia forja cuando esté disponible, y confirma que cada comando que llama existe y se ejecuta localmente en el mismo orden. Para GitLab, usa CI Lint con la configuración incluida expandida. Para GitHub, inspecciona el flujo de trabajo en el editor de Actions o haz push en una rama cuando el usuario haya autorizado ese cambio externo; un analizador YAML genérico no puede validar expresiones de GitHub o semántica de flujo de trabajo. Enumera los secretos que el pipeline necesita, con el comando para agregar cada uno, sin ejecutar ese comando. Confirma que la matriz coincida con cada línea de lanzamiento compatible y que cada trabajo tenga un tiempo de espera y participe en la cancelación de ejecuciones reemplazadas cuando sea seguro.
Paso 8: Presentar el resultado
Muestra el archivo generado, un breve resumen de lo que se detectó y decidió, la lista de secretos a configurar y cualquier cosa que quede para que el usuario establezca a nivel de repositorio o proyecto, como protección de ramas o aprobadores de entorno, nombrando la habilidad que lo posee en lugar de intentarlo aquí.
Reglas que posee esta habilidad
R-CI-01: La CI se ejecuta en cada push a la rama predeterminada y en cada solicitud de cambio
R-CI-02: La CI ejecuta los mismos comandos de lint, prueba y compilación que la guía de contribución proporciona a los humanos
R-CI-03: La matriz de pruebas cubre cada versión de runtime que el proyecto afirma soportar
R-CI-04: Los cachés de dependencias se clavan en el archivo de bloqueo
R-CI-05: Cada trabajo tiene un tiempo de espera, y las ejecuciones reemplazadas para la misma rama se cancelan