Del repositorio vacío a una URL pública

Antes de empezar. En esta primera sesión crearás la estructura inicial del portfolio profesional y configurarás su flujo de despliegue automatizado. Para ello necesitarás tu cuenta de GitHub institucional, el cliente de Git configurado en tu entorno local y un editor de código. El backend se desarrollará en paralelo en el módulo de Servidor; para este taller basta con un documento HTML base que permita validar el canal de entrega continua.

---

Se explica

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

Criterios de evaluación técnica entre módulos

Ambos módulos se imparten de forma coordinada. En Desarrollo Web en Entorno Servidor se diseña, implementa y prueba la lógica de negocio y los servicios de la aplicación; en Proyecto Intermodular se aprende a planificar, revisar, validar y desplegar ese trabajo siguiendo metodologías profesionales de ingeniería del software. Cada herramienta del flujo de automatización se introduce y analiza antes de su aplicación práctica.

La consecuencia directa es que el mismo proyecto es auditado desde dos dimensiones complementarias:

Un proyecto puede presentar una interfaz atractiva o un backend avanzado y, sin embargo, no superar este módulo si carece de metodología, control de versiones o revisiones de código. De igual forma, una implementación inicial sencilla con un flujo de integración impecable y rigurosamente documentado obtiene la máxima calificación.

El flujo de trabajo profesional: del requisito a producción

Durante todo el ciclo de desarrollo, cualquier modificación en el software debe seguir un flujo riguroso compuesto por siete etapas secuenciales. En esta sesión se establece la base del despliegue automatizado; en la siguiente se protegerá la rama principal y se practicará el flujo colaborativo, y en la sesión 3 se incorporarán las pruebas automatizadas de validación estática:

1. IssueDefinición clara de un requisito o tarea técnica con criterios de aceptación explícitos.
2. Rama de funcionalidadLínea de desarrollo aislada que permite trabajar y experimentar sin alterar la versión estable de producción.
3. Commit atómicoRegistro de un cambio autocontenido y justificado mediante un mensaje descriptivo en modo imperativo.
4. Pull requestPropuesta formal de integración para auditar las diferencias de código e iniciar el proceso de validación.
5. Validación automática (CI)Ejecución desasistida de pruebas, analizadores de código y comprobaciones de integridad en GitHub Actions. (Se incorpora en la sesión 3).
6. Revisión por paresInspección manual del código por parte de otro miembro del equipo, quien aprueba o solicita modificaciones.
7. Despliegue continuo (CD)Tras la fusión autorizada en la rama principal, el pipeline publica automáticamente la nueva versión en el entorno público.

Flujo de integración continua (Pipeline)

El protocolo estandarizado e inmutable que recorre cualquier cambio de código desde su formulación hasta su puesta en producción. Se define como un proceso cerrado porque no admite excepciones manuales ni atajos: si un cambio pudiera llegar a producción sin superar las validaciones y revisiones establecidas, el equipo carecería de una política de calidad real, dependiendo de la falibilidad de la intervención humana.

Justificación del despliegue temprano: patrón Walking Skeleton

Un enfoque intuitivo pero erróneo consiste en postergar el despliegue del software hasta disponer de una interfaz avanzada y un backend completo. En ingeniería del software se adopta el principio contrario: la implantación temprana de un Walking Skeleton (esqueleto funcional mínimo).

La experiencia demuestra que la mayoría de incidencias críticas en un despliegue no proceden de la lógica del código fuente, sino de la infraestructura subyacente: errores de configuración de red, permisos de acceso insuficientes, variables de entorno mal declaradas, conflictos de nombres de dominio o directivas de empaquetado incorrectas.

Resolver estas fricciones de infraestructura desde la primera sesión con un documento elemental garantiza aislar los problemas de configuración de los problemas de lógica de aplicación, aplicando el principio fundamental de fallo temprano (fail-early).

Infraestructura de alojamiento y automatización con GitHub Pages

GitHub Pages y Actions

GitHub Pages es un servicio de alojamiento para sitios web estáticos (HTML, CSS y JavaScript) que se sirve directamente desde un repositorio de Git. En lugar de limitarse a una copia pasiva de archivos, la configuración profesional de GitHub Pages se gestiona mediante GitHub Actions, integrando Infraestructura como Código (IaC). Cada evento de integración en la rama principal desencadena la ejecución de un flujo de trabajo declarativo que empaqueta y publica el contenido de forma automatizada.

---

Se trabaja

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

Bloque A · Creación del repositorio y estructura inicial

Trabajo individual. Este repositorio constituirá la base permanente de tu portfolio profesional.

1 · Creación del repositorio en GitHub. Accede a github.com y selecciona New repository (o el icono «+» superior derecho).

2 · Clonación en el entorno local. En la interfaz del repositorio, pulsa el botón Code, copia la URL bajo la pestaña HTTPS y ejecuta en tu terminal de trabajo:

git clone https://github.com/TU-USUARIO/portfolio.git
cd portfolio

3 · Creación del documento HTML inicial de verificación. Crea el archivo index.html en la raíz del repositorio con una estructura HTML5 válida y mínima. Su función técnica es servir de comprobante para certificar que el servidor web entrega correctamente los archivos:

<!doctype html>
<html lang="es">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Portfolio de Nombre Apellido</title>
  </head>
  <body>
    <h1>Nombre Apellido</h1>
    <p>Documento inicial para verificar la automatización del despliegue continuo.</p>
  </body>
</html>

En esta fase inicial es prioritario no añadir hojas de estilo ni scripts complejos. El propósito exclusivo del ejercicio es validar la conectividad de extremo a extremo del canal de entrega continua. La maquetación semántica y los componentes visuales se incorporarán progresivamente a partir de la sesión 3, canalizando cada incremento mediante ramas y revisiones formales.

4 · Registro y envío del cambio al repositorio remoto.

git add index.html
git commit -m "Anadir estructura inicial del documento index.html"
git push

5 · Estándares profesionales para mensajes de commit. A partir de este momento, los mensajes de confirmación deben ajustarse rigurosamente a las convenciones estándar de la industria:

Resolución de incidencias de autenticación en git push

GitHub no admite contraseñas de cuenta convencionales para operaciones remotas por HTTPS. Si el comando solicita credenciales y falla, debe utilizarse Git Credential Manager (integrado de forma nativa en Git para Windows, que autentica mediante el navegador) o generar un Personal Access Token (PAT) con permisos de lectura y escritura en repositorios desde Settings → Developer settings → Personal access tokens.

Bloque B · Automatización del despliegue con GitHub Pages

Procedimiento guiado · Configuración del origen de integración continua

1 · Acceso a la configuración del servicio. En la interfaz del repositorio en GitHub, accede a la pestaña Settings (en la barra superior). En el menú lateral izquierdo, dentro de la sección Code and automation, selecciona Pages.

2 · Configuración del origen de compilación (Build and deployment). En el selector desplegable Source, modifica la opción por defecto (Deploy from a branch) y selecciona GitHub Actions.

3 · Selección de la plantilla de flujo de trabajo. En las sugerencias presentadas bajo Suggested workflows, localiza la plantilla Static HTML y pulsa Configure. Se abrirá el editor web mostrando el archivo de definición static.yml.

4 · Confirmación e integración del workflow. Pulsa el botón superior Commit changes…, selecciona la opción Commit directly to the main branch y confirma pulsando Commit changes.

En este primer paso no debe alterarse la configuración predeterminada del YAML. Dicha plantilla está preconfigurada para empaquetar y publicar la raíz del repositorio, que es donde se encuentra el archivo index.html. En la sesión 3 se profundizará en la edición y personalización de flujos de trabajo propios.

5 · Monitorización de la ejecución en GitHub Actions. Accede a la pestaña Actions del repositorio. Observarás una ejecución en curso identificada con un indicador amarillo. Al hacer clic sobre ella y acceder al trabajo (job) denominado deploy, podrás inspeccionar en tiempo real los cuatro pasos que componen el pipeline: checkout del código, configuración del entorno de Pages, empaquetado de artefactos y publicación.

6 · Verificación del entorno de producción. Una vez que la ejecución finalice con estado de éxito (indicador verde), regresa a Settings → Pages. En el panel superior se indicará la dirección pública bajo la leyenda Your site is live at, con un formato similar a https://tu-usuario.github.io/portfolio/. Accede a dicha URL para verificar que el documento HTML se visualiza en el navegador.

Diagnóstico de errores habituales en el despliegue

La URL responde con código de estado HTTP 404. En una primera publicación, el enrutamiento DNS y el aprovisionamiento de certificados SSL pueden requerir entre uno y dos minutos tras la finalización del workflow. Si el error persiste, comprueba que la ruta en el navegador incluye la barra final requerida (/portfolio/).

HTTP 404 pese a que Actions finalizó en verde. El archivo de entrada debe llamarse con exactitud index.html (en minúsculas y sin tildes) y encontrarse estrictamente en la raíz del repositorio, no dentro de un subdirectorio.

No se muestra la sugerencia de plantilla Static HTML. Haz clic en browse all workflows y utiliza el campo de búsqueda escribiendo static. Selecciona la opción oficial denominada «Deploy static content to Pages».

No se inicia ninguna ejecución en Actions. El origen de implementación no se guardó correctamente. Vuelve al paso 2 y asegúrate de que el selector Source indica GitHub Actions.

Bloque C · Análisis técnico del workflow de despliegue

Trabajo individual · Inspección de la infraestructura como código

El archivo generado en el paso anterior se ha confirmado remotamente en la rama principal. Para sincronizar tu espacio de trabajo local con el repositorio remoto, ejecuta:

git pull

Examina el nuevo archivo ubicado en .github/workflows/static.yml:

name: Deploy static content to Pages

on:
  push:
    branches: ['main']
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Flujo de trabajo (Workflow)

Un descriptor declarativo en formato YAML que define qué procesos automatizados debe ejecutar GitHub Actions, bajo qué circunstancias de disparo y con qué permisos y dependencias. Al residir dentro del sistema de control de versiones, la configuración de despliegue goza de trazabilidad, puede auditarse en revisiones de código y evoluciona al mismo ritmo que la aplicación.

on: push: branches: ['main']

Disparador por evento de código. Cualquier incorporación o fusión confirmada en la rama main activa automáticamente el proceso de compilación y despliegue.

workflow_dispatch

Disparador manual. Habilita la interfaz interactiva con el botón Run workflow en GitHub Actions para ejecutar el despliegue bajo demanda sin necesidad de realizar modificaciones en el código.

Ausencia de la directiva pull_request

Este flujo se ejecuta exclusivamente sobre el código ya integrado en la rama principal. Las pull requests aún no disponen de validaciones previas a la fusión; dicha protección constituirá el núcleo de la Unidad 2.

permissions: id-token: write y pages: write

Asignación de privilegios de ejecución mediante autenticación OIDC (OpenID Connect). El runner obtiene un token efímero de corta duración con privilegios acotados exclusivamente a la publicación en Pages. No se requieren secretos estáticos de larga duración (PAT) almacenados en el repositorio.

path: '.'

Ruta del directorio que se empaqueta como artefacto publicable. En este proyecto corresponde a la raíz (.). En aplicaciones que incorporan empaquetadores o compiladores, esta directiva apuntaría al directorio de distribución (por ejemplo, ./dist).

concurrency: group: 'pages'

Control de concurrencia para evitar condiciones de carrera (race conditions). Si se suceden varias confirmaciones consecutivas, se serializa su ejecución para garantizar que los despliegues se apliquen en estricto orden cronológico sin corromper el estado del sitio.

¿Qué dos eventos distintos pueden activar la ejecución de este workflow?

Si se confirma un commit en local sin ejecutar git push, ¿se desencadena el despliegue? Justifica técnicamente la respuesta.

¿Por qué no es necesario configurar un secreto de repositorio en Settings para que este workflow pueda publicar?

Si se abre una pull request, ¿se ejecuta este workflow? ¿En qué directiva del archivo se evidencia?

Bloque C-bis · Diagnóstico de fallos: error de pipeline frente a fallo funcional

Trabajo individual · Práctica de diagnóstico y observabilidad

Una vez comprendida la estructura del archivo de automatización, provocaremos deliberadamente dos fallos de distinta naturaleza técnica para analizar la diferencia entre un fallo en la infraestructura del pipeline y un fallo funcional del servicio.

Caso 1 · Fallo de infraestructura en el pipeline (Ruta de artefacto inexistente). Modifica .github/workflows/static.yml alterando la ruta del paso de empaquetado:

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

Envía la modificación a la rama principal:

git add .github/workflows/static.yml
git commit -m "Simular error de infraestructura en la ruta del artefacto"
git push

Accede a la pestaña Actions. La ejecución concluirá con un indicador de error (aspa roja). Al inspeccionar el trabajo deploy, observarás que el paso Upload artifact ha fallado y que los pasos sucesivos han cancelado su ejecución. El registro técnico explicita que el directorio especificado no existe en el sistema de archivos del runner.

A continuación, sin modificar el código, accede a la URL pública de tu portfolio. El sitio continuará respondiendo con la versión anterior. En entornos de entrega continua, los despliegues son operaciones atómicas: si una fase del pipeline falla antes de la publicación, la versión estable previa permanece inalterada en producción.

Restaura el archivo devolviendo la directiva a path: '.' y confirma el cambio:

git add .github/workflows/static.yml
git commit -m "Restaurar ruta raiz para empaquetado de artefactos"
git push

La nueva ejecución volverá a completarse con éxito.

Caso 2 · Fallo semántico con pipeline exitoso (Ausencia del archivo de entrada). Modifica ahora el nombre del documento principal mediante Git:

git mv index.html inicio.html
git commit -m "Renombrar documento principal a inicio.html"
git push

Esta ejecución concluye con estado de éxito (verde). Los cuatro pasos se completan sin advertencias técnicas. Sin embargo, al abrir la URL pública en el navegador, el servidor web responderá con un error HTTP 404. (Si el navegador muestra la versión en caché, fuerza la recarga sin caché mediante Ctrl+Shift+R).

No existe contradicción técnica: el pipeline ejecutó fielmente las instrucciones declaradas (empaquetar el contenido del repositorio y desplegarlo). Lo que ha fallado es el cumplimiento de los estándares del servidor web, el cual requiere un archivo de entrada predeterminado denominado index.html. Este ejercicio evidencia por qué un estado verde en el pipeline certifica la ejecución de los comandos, pero no valida por sí solo la corrección funcional del producto.

Restablece el nombre correcto del archivo y confirma el cambio:

git mv inicio.html index.html
git commit -m "Restablecer index.html como punto de entrada de la aplicacion"
git push

¿En qué paso concreto falló el Caso 1 y cuál fue el mensaje exacto registrado en el log?

Mientras la ejecución del Caso 1 permanecía en error, ¿qué mostraba la URL pública y qué principio de despliegue justifica ese comportamiento?

En el Caso 2 GitHub Actions finalizó en verde pese al error 404. ¿Qué validó la máquina y qué quedó sin comprobar?

¿Cuál de los dos escenarios representa un mayor riesgo en un entorno de producción profesional y por qué motivos de observabilidad?

Pautas de resolución ante discrepancias en el estado

La URL pública persiste con error 404 tras corregir el código. Consulta la pestaña Actions: cada corrección inicia una nueva ejecución que requiere tiempo de compilación y distribución en red. Una vez finalizada en verde, limpia la caché del navegador recargando la página.

Desorientación en el árbol de confirmaciones. Ejecuta git log --oneline --graph para inspeccionar el historial cronológico. Para deshacer un commit sin alterar el historial, git revert HASH genera una confirmación inversa limpia.

Comportamiento del sistema de archivos según el sistema operativo. Los sistemas de archivos en Windows y macOS son a menudo insensibles a mayúsculas y minúsculas (case-insensitive), mientras que los servidores de producción basados en Linux distinguen estrictamente entre index.html e Index.html. Se recomienda utilizar siempre nombres en minúsculas para prevenir discrepancias de despliegue.

Bloque D · Documentación técnica del proyecto en README

Fase de consolidación · Documentación técnica del repositorio

Actualiza el archivo README.md incorporando la información técnica esencial del proyecto. En esta primera sesión se realiza la modificación directamente sobre la rama main; a partir de la próxima sesión la rama principal quedará protegida y cualquier cambio deberá canalizarse mediante ramas de funcionalidad y pull requests.

git add README.md
git commit -m "Documentar arquitectura de despliegue y URL publica en README"
git push

Al inspeccionar la pestaña Actions se verificará una nueva ejecución desatendida provocada por el evento de actualización de la rama main.

Bloque E · Modelos de flujo de trabajo y colaboración en la industria

Trabajo de investigación y síntesis técnica · Tarea individual

Los procedimientos adoptados en este módulo (descomposición en issues, ramificación, revisión por pares y despliegue automatizado) se corresponden con los estándares metodológicos de la ingeniería de software actual. Sin embargo, los equipos profesionales adaptan estas prácticas a su arquitectura y cadencia de entrega.

Selecciona una de las siguientes referencias de la industria para analizarla en detalle:

Entregable técnico. Genera un documento en formato PDF de una página y almacénalo en el repositorio bajo la ruta docs/flujo-de-trabajo.pdf. Debe recoger un análisis personal estructurado:

git add docs/flujo-de-trabajo.pdf
git commit -m "Anadir analisis tecnico sobre modelos de flujo de trabajo"
git push

Ampliación conceptual: Métricas DORA

El consorcio de investigación DORA (DevOps Research and Assessment) analiza anualmente los factores que determinan el rendimiento de los equipos de ingeniería de software. Sus cuatro métricas clave son: la frecuencia de despliegue (deployment frequency), el tiempo de entrega de cambios (lead time for changes), la tasa de fallos en producción (change failure rate) y el tiempo medio de recuperación (time to restore service). Ninguna de estas métricas evalúa líneas de código brutas ni horas de presencia, sino la agilidad y estabilidad del proceso de entrega continua.

Bloque F · Práctica complementaria: Despliegue en Microsoft Azure

Opcional · Exploración práctica de provisión cloud

El portfolio ya dispone de un entorno de producción activo en GitHub Pages. Este bloque complementario introduce el aprovisionamiento en un proveedor de infraestructura en la nube (cloud provider) comercial como Microsoft Azure, anticipando la arquitectura requerida para el backend en evaluaciones posteriores.

Al concluir este bloque dispondrás de dos pipelines independientes publicando concurrentemente el mismo repositorio en dos plataformas distintas. Ambas URLs serán plenamente funcionales.

1 · Aprovisionamiento de la suscripción académica.

1. Accede a azure.microsoft.com/es-es/free/students.
2. Selecciona Empezar gratis e inicia sesión con las credenciales de tu correo institucional, acreditando la condición de estudiante.
3. Acepta las condiciones del servicio. Esta modalidad no requiere tarjeta de crédito.
4. Accede a portal.azure.com y verifica en la sección Suscripciones (Subscriptions) la presencia activa de la suscripción Azure for Students.

Incidencias en la validación de la cuenta educativa

Si la verificación académica no se completa inmediatamente, comprueba haber utilizado la cuenta institucional del centro educativo. Si el dominio requiere validación adicional por parte del proveedor, no interrumpe el desarrollo del curso, ya que el flujo principal de CI/CD opera sobre GitHub Pages.

2 · Creación del recurso en Azure. En la barra superior del portal de Azure, busca Static Web Apps y pulsa Crear (Create).

3 · Configuración de parámetros básicos. Cumplimenta el formulario con los siguientes valores:

4 · Vinculación con GitHub. Pulsa Iniciar sesión con GitHub y concede los permisos de autorización a Azure. A continuación, selecciona en los menús desplegables:

5 · Parámetros de compilación (Build Presets). Especifica la configuración técnica para sitios estáticos sin paso de empaquetado intermedio:

6 · Revisión y provisión. Accede a la pestaña Revisar y crear y confirma pulsando Crear. El aprovisionamiento de la infraestructura tomará entre uno y dos minutos. Al finalizar, pulsa Ir al recurso.

7 · Monitorización del despliegue. Regresa a tu repositorio en GitHub y accede a la pestaña Actions. Observarás un nuevo flujo de trabajo generado automáticamente por Azure en ejecución.

8 · Comprobación de la URL pública. Tras completarse la ejecución con éxito, regresa a la vista general del recurso en el portal de Azure. En el campo URL figurará el dominio asignado (con formato nombre-aleatorio.azurestaticapps.net). Accede a dicho enlace para comprobar que el sitio web se encuentra en línea.

Diagnóstico de incidencias en Azure Static Web Apps

La URL muestra una página de bienvenida de Azure o código 404. El despliegue inicial puede requerir unos instantes adicionales para propagar el contenido a través de la red perimetral (CDN). Comprueba en Actions que el workflow ha finalizado satisfactoriamente.

El repositorio no aparece en la selección de GitHub. La aplicación OAuth de Azure requiere autorización de lectura sobre tu cuenta de GitHub. Comprueba los permisos concedidos en GitHub bajo Settings → Applications → Authorized OAuth Apps.

El workflow finaliza en error. Revisa el registro de ejecución en GitHub Actions. La causa habitual se debe a rutas incorrectas en App location u Output location en el paso 5.

Conflicto con el nombre del recurso. Los nombres de los recursos deben ser globalmente únicos en el espacio de nombres de Azure. Añade un sufijo numérico o tus iniciales al nombre.

---

Cierre

15 minutos · evaluación y consolidación de competencias

Respuestas a la autoevaluación

1 · Porque la mayor parte de las incidencias críticas en un despliegue corresponden a la configuración de infraestructura, permisos y dominios, y no al código. Resolver estos aspectos tempranamente sobre un Walking Skeleton evita acumular problemas en fases avanzadas del desarrollo.

2 · El archivo es proporcionado como plantilla oficial por GitHub al configurar la opción Static HTML, y se incorpora al repositorio mediante una confirmación directa en la rama main realizada desde la interfaz web.

3 · GitHub detecta el evento push en la rama main, inicializa un runner limpio en un contenedor Linux, descarga el repositorio, empaqueta los archivos como artefacto de Pages y los publica mediante credenciales efímeras OIDC.

4 · Porque las directivas de protección de ramas y reglas avanzadas de pull request en GitHub son gratuitas exclusivamente en repositorios públicos en cuentas personales, y porque un portfolio profesional está destinado a ser público.

5 · No. El descriptor actual restringe el disparador exclusivamente al evento push en la rama main. Una pull request no fusionada no altera dicha rama; las validaciones automáticas sobre pull requests se implementarán en la Unidad 2.

6 · Ha verificado que todos los comandos declarados concluyeron con código de salida 0 (sin excepciones de infraestructura). No ha verificado la existencia del punto de entrada requerido por el servidor web (index.html) ni la corrección funcional del contenido.