El primer flujo de integración continua

Antes de empezar. Ya has trabajado con issues, ramas de funcionalidad y revisión por pares. En esta sesión el portfolio incorpora su primera validación automatizada, ejecutada sobre cada propuesta de integración antes de que el código alcance la rama principal. El backend continúa su desarrollo en el repositorio del módulo de Servidor.

---

Se explica

25 minutos · explicación conceptual y demostración técnica

Ausencia de validación previa a la integración

El único proceso automatizado disponible hasta ahora es el despliegue, que presenta dos limitaciones estructurales. La primera afecta a su posición en el ciclo de vida: se ejecuta después de la fusión, cuando el cambio ya forma parte de main, de modo que cualquier diagnóstico que emitiera llegaría con el defecto ya publicado. La segunda afecta a su alcance: el flujo de publicación empaqueta los archivos del repositorio y los transfiere al servidor. Un documento con etiquetas sin cerrar, imágenes sin texto alternativo o enlaces internos no resolubles supera ese proceso con estado de éxito, porque la operación de transferencia se ha completado correctamente.

Conviene formalizar la distinción, dado que estructura el resto del ciclo de vida del software:

En esta sesión se implementa la segunda mediante un workflow redactado manualmente: a diferencia del flujo de publicación, esta definición no la genera ningún asistente del portal.

El entorno de ejecución: runners efímeros y reproducibilidad

Runner

Máquina virtual que GitHub aprovisiona para ejecutar un workflow y destruye al finalizar. Su sistema de archivos parte de una imagen base estandarizada: no contiene el proyecto, ni las dependencias instaladas en la estación de trabajo local, ni la configuración personal de quien desarrolla. Cada ejecución parte del mismo estado inicial conocido.

Esta naturaleza efímera determina las dos reglas que previenen la mayoría de los errores de esta sesión:

La consecuencia metodológica es la reproducibilidad: al partir de un estado inicial conocido, el resultado obtenido en el runner es reproducible por cualquier persona o sistema que ejecute la misma definición. Un entorno local, por el contrario, acumula dependencias globales, variables de entorno y versiones no declaradas. Esa divergencia progresiva entre entornos (configuration drift) constituye el origen técnico del argumento «en mi equipo funciona», que un pipeline de integración continua invalida como criterio de aceptación.

Estructura declarativa de un workflow

La especificación de GitHub Actions se articula en torno a cuatro elementos:

on

Declara los eventos que desencadenan la ejecución. En esta implementación serán la apertura o actualización de una pull request y la integración de cambios en main.

jobs

Unidades de trabajo independientes. Cada job se aprovisiona en su propia máquina virtual y se ejecuta en paralelo, salvo que se declare una dependencia explícita mediante needs. Cada job se publica como un check verificable en la pull request.

steps

Secuencia ordenada de etapas dentro de un job. El fallo de una etapa interrumpe la ejecución de las restantes.

uses frente a run

uses invoca una acción reutilizable publicada por terceros; run ejecuta una instrucción en el intérprete de comandos del runner.

---

Se trabaja

140 minutos · trabajo práctico guiado sobre el proyecto base

Bloque A · Implementación del workflow de validación

Antes de abrir el editor, verifica la disponibilidad del entorno de ejecución. Node.js permite ejecutar JavaScript fuera del navegador, npm es su gestor de paquetes y npx el ejecutor que invoca un paquete sin instalarlo de forma permanente en el sistema. En este módulo intervienen exclusivamente como herramientas de análisis estático del marcado; no guardan relación con el desarrollo del backend. Ejecuta node --version y npm --version en la terminal: la versión requerida es Node 22, idéntica a la declarada en el workflow, de modo que el entorno local y el del runner sean equivalentes. Si la instalación acaba de realizarse, abre una terminal nueva, ya que una sesión previa conserva las variables de entorno anteriores. En PowerShell, la política de ejecución puede bloquear npm.ps1; en ese caso invoca npm.cmd y npx.cmd.

Ambos archivos se ubican en la raíz del repositorio del portfolio: .htmlvalidate.json y .github/workflows/ci.yml. En las sesiones siguientes, los nuevos trabajos de validación se incorporarán dentro de ese mismo ci.yml, bajo la clave jobs, y no en archivos independientes. El workflow de despliegue de la sesión 1 se conserva sin modificaciones: uno publica y el otro valida, y ambos resultan necesarios.

Trabajo individual, siguiendo el flujo de integración establecido

1 · Issue y rama de funcionalidad. Crea una issue titulada «Añadir un workflow de CI que valide el HTML», con el siguiente criterio de aceptación: cada pull request muestra un check denominado HTML válido, y ese check falla cuando el marcado contiene errores. A continuación, genera la rama correspondiente:

git switch main
git pull
git switch -c 7-ci-html

2 · Configuración del analizador estático. Crea en la raíz el archivo .htmlvalidate.json:

{
  "extends": ["html-validate:recommended"]
}

Esa declaración selecciona el conjunto de reglas aplicables. Sin archivo de configuración, la herramienta carece de criterio normativo con el que evaluar el documento.

3 · Definición del workflow. Crea .github/workflows/ci.yml, junto al workflow de despliegue y no dentro de él: son procesos con responsabilidades distintas y se declaran en archivos independientes.

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  html:
    name: HTML válido
    runs-on: ubuntu-latest
    steps:
      - name: Descargar el repositorio
        uses: actions/checkout@v4

      - name: Preparar Node
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Validar el HTML
        run: npx --yes html-validate@9 "**/*.html"

4 · Análisis de la definición antes de integrarla. Responde sin consultar documentación externa:

¿Cuántos jobs define el archivo y con qué nombre aparecerá el check en la pull request?

¿Qué etapas invocan una acción de terceros y cuál ejecuta una instrucción propia?

Si se suprimiera la etapa de checkout, ¿qué error se produciría y cuál sería su causa?

5 · Integración y apertura de la pull request.

git add .github/workflows/ci.yml .htmlvalidate.json
git commit -m "Anadir un workflow de CI que valida el HTML"
git push -u origin 7-ci-html

Abre la pull request incluyendo Closes #7 en su descripción. La definición queda sometida a sí misma: la propia pull request que incorpora el CI es validada por él. En la sección de comprobaciones aparece un único check, el recién declarado; el workflow de despliegue no figura porque su evento de activación no contempla pull_request. Con ello queda cubierta la etapa de validación que la sesión anterior identificó como ausente en el ciclo.

Si el check resulta fallido en la primera ejecución

Es el resultado más frecuente e indica que el analizador está evaluando efectivamente el documento. Abre la ejecución en la pestaña Actions, accede a la etapa «Validar el HTML» y localiza las líneas que comienzan por la ruta del archivo: cada una indica el número de línea y la regla incumplida. Corrige sobre la misma rama, confirma y envía los cambios; el check se reejecuta de forma automática.

Bloque B · Provocación controlada de fallos

Ejecución simultánea sobre la misma rama

Un pipeline cuyo comportamiento ante el error no ha sido observado no ofrece garantías operativas. Introduce las tres alteraciones siguientes, de forma individual, y analiza el diagnóstico que emite cada una:

Restablece el estado correcto y verifica que el check vuelve a completarse con éxito antes de continuar.

Bloque C · Conversión del check en requisito de fusión

Trabajo individual en la configuración del repositorio

Una comprobación que informa pero no condiciona la integración termina siendo ignorada. La configuración siguiente la convierte en comprobación obligatoria (required status check).

1. Fusiona previamente la pull request del bloque A, de modo que el check conste en el historial de main.
2. Accede a Settings → Rules → Rulesets → main protegida → Edit.
3. En Require status checks to pass —la regla que en la sesión anterior no pudo configurarse porque la lista de comprobaciones disponibles estaba vacía— selecciona Add checks e incorpora HTML válido.
4. Guarda la configuración.

Verificación: crea una rama con un error de marcado deliberado, abre la pull request y comprueba que la acción de fusión queda bloqueada. Cierra esa pull request sin fusionarla.

Bloque D · Primera sección del portfolio definitivo

Trabajo individual, con la validación automática ya activa

Concluye la fase del documento mínimo de verificación. Selecciona del tablero la issue correspondiente a la cabecera e implementa la primera sección real del portfolio con estructura semántica: un encabezado con navegación, un contenido principal y un pie de página. Sin hojas de estilo todavía: en esta fase el objetivo es la corrección estructural del documento.

---

Cierre

15 minutos · comprobación del resultado

Ver respuestas

1 · Porque el runner se aprovisiona a partir de una imagen base que no contiene el código fuente del repositorio; su obtención debe declararse de forma explícita.

2 · uses invoca una acción reutilizable ya publicada por terceros; run ejecuta una instrucción propia en el intérprete de comandos del runner.

3 · El runner, por tratarse de un entorno reproducible que parte de un estado inicial conocido. La estación local acumula configuración no declarada que ningún otro sistema comparte.

4 · Porque una advertencia que no condiciona la integración se omite en cuanto existe presión de entrega. Una comprobación no vinculante deja de ejercer función de control de calidad.

5 · En la etapa marcada como fallida, comenzando la lectura por sus últimas líneas.