{}
Aprende diseño y desarrollo web
Cursos gratuitos interactivos

GitHub Pages en serio: despliegue estable para portfolio, documentación y proyectos estáticos

Aprende a publicar con GitHub Pages sin improvisar: estructura de repositorio, ramas de publicación, dominios personalizados, HTTPS y diagnóstico de fallos comunes.

GitHub Pages parece simple hasta que entras en un flujo real: repositorio de usuario vs proyecto, rutas base rotas, dominio personalizado y despliegues que fallan por detalles pequeños.

La meta de esta lección es que publiques de forma reproducible, sepas exactamente qué rama alimenta tu sitio y puedas diagnosticar por qué una build no llega a producción.

Cuando termines, podrás conectar esta publicación con colaboración por PR en <a href="/curso/git-github/leccion/git-github-remotos-y-pull-requests-colaboracion">remotos y pull requests</a> para tener un flujo completo de equipo.

  • Antes de tocar Settings, define el contrato técnico del despliegue.
  • GitHub Pages puede publicar desde la rama principal, desde una carpeta concreta (como <code>/docs</code>) o desde una rama dedicada. Elegir mal ese origen es una causa típica de despliegues inconsistentes.
  • En proyectos con build (Astro, Vite, etc.), lo más limpio es separar fuente y artefacto publicado. Así evitas mezclar código de desarrollo con salida compilada y reduces errores de merge.
  • Repositorio de usuario: <code>usuario.github.io</code> para sitio principal.
  • Repositorio de proyecto: URL con subruta del nombre del repo.

Modelo de publicación: qué se publica y desde dónde

Antes de tocar Settings, define el contrato técnico del despliegue.

GitHub Pages puede publicar desde la rama principal, desde una carpeta concreta (como <code>/docs</code>) o desde una rama dedicada. Elegir mal ese origen es una causa típica de despliegues inconsistentes.

En proyectos con build (Astro, Vite, etc.), lo más limpio es separar fuente y artefacto publicado. Así evitas mezclar código de desarrollo con salida compilada y reduces errores de merge.

  • Repositorio de usuario: <code>usuario.github.io</code> para sitio principal.
  • Repositorio de proyecto: URL con subruta del nombre del repo.
  • Rama de publicación definida y documentada para todo el equipo.
  • Base path alineada con el tipo de repositorio.

Dominio personalizado, DNS y HTTPS sin sustos

Publicar no termina cuando aparece la URL de GitHub Pages.

Si conectas dominio propio, el archivo <code>CNAME</code> y los registros DNS deben coincidir exactamente. Un detalle mal escrito deja el sitio accesible por una URL y roto por la otra.

Activa HTTPS solo cuando la resolución DNS esté estable. Si fuerzas HTTPS demasiado pronto, puedes generar errores temporales difíciles de interpretar para quien no conoce el ciclo de propagación DNS.

Fallos frecuentes y diagnóstico rápido

Un buen flujo no evita todos los errores, pero sí acorta su resolución.

Errores típicos: archivos fuera de la carpeta configurada, rutas absolutas incorrectas, build que genera en otro directorio y ausencia de archivo inicial cuando el proyecto lo requiere.

Tu trabajo profesional no es solo publicar, sino dejar un checklist de diagnóstico para que otro miembro del equipo pueda recuperar el servicio sin depender de ti.

Git & GitHub
08

GitHub Pages en serio: despliegue estable para portfolio, documentación y proyectos estáticos

Aprende a publicar con GitHub Pages sin improvisar: estructura de repositorio, ramas de publicación, dominios personalizados, HTTPS y diagnóstico de fallos comunes.

¿Cuánto sabes de Git & GitHub?

Código del tema: Pages · DNS · despliegue

📘 Teoría

Modelo de publicación: qué se publica y desde dónde

Antes de tocar Settings, define el contrato técnico del despliegue.

GitHub Pages puede publicar desde la rama principal, desde una carpeta concreta (como /docs) o desde una rama dedicada. Elegir mal ese origen es una causa típica de despliegues inconsistentes.

En proyectos con build (Astro, Vite, etc.), lo más limpio es separar fuente y artefacto publicado. Así evitas mezclar código de desarrollo con salida compilada y reduces errores de merge.

  • Repositorio de usuario: usuario.github.io para sitio principal.
  • Repositorio de proyecto: URL con subruta del nombre del repo.
  • Rama de publicación definida y documentada para todo el equipo.
  • Base path alineada con el tipo de repositorio.

Dominio personalizado, DNS y HTTPS sin sustos

Publicar no termina cuando aparece la URL de GitHub Pages.

1

Si conectas dominio propio, el archivo CNAME y los registros DNS deben coincidir exactamente. Un detalle mal escrito deja el sitio accesible por una URL y roto por la otra.

2

Activa HTTPS solo cuando la resolución DNS esté estable. Si fuerzas HTTPS demasiado pronto, puedes generar errores temporales difíciles de interpretar para quien no conoce el ciclo de propagación DNS.

Comprobación mínima de repo antes de activar Pages
git status
git branch --show-current
git remote -v

Fallos frecuentes y diagnóstico rápido

Un buen flujo no evita todos los errores, pero sí acorta su resolución.

1

Errores típicos: archivos fuera de la carpeta configurada, rutas absolutas incorrectas, build que genera en otro directorio y ausencia de archivo inicial cuando el proyecto lo requiere.

2

Tu trabajo profesional no es solo publicar, sino dejar un checklist de diagnóstico para que otro miembro del equipo pueda recuperar el servicio sin depender de ti.

🧭 Visuales clave

Flujo de publicación de GitHub Pages

Muestra la secuencia técnica mínima para desplegar y validar un sitio estable en GitHub Pages.

Diagrama del flujo de publicación en GitHub Pages desde rama de código hasta dominio final con HTTPS

🧪 Aprende probando

Ejemplo Ejemplo guiado: preparar rama de publicación Crea una rama específica para el contenido estático publicado.
⌄
Ejemplo Ejemplo guiado: registrar dominio personalizado Añade archivo CNAME al contenido publicado.
⌄

🏁 Retos

Reto Reto: checklist de despliegue reproducible Escribe un checklist mínimo para validar que el despliegue está correcto antes de anunciar release.
⌄

🧰 Recursos

Enlaces útiles

GitHub Docs - Acerca de GitHub Pages GitHub Docs - Configurar dominio personalizado GitHub Docs - Solucionar errores de compilación Jekyll
Test

Comprueba tus conocimientos con un test sobre Git & GitHub.

Test de Git & GitHub
Recursos del curso 15
📘 Glosario 🎧 Audios 📄 PDFs 🖼️ Infografías 🎬 Vídeos 🔗 Enlaces 🧠 Flashcards
‹
Lección 07
Remotos, forks y pull requests que un equipo agradece
Lección 09
Integración GitHub + VS Code: flujo diario sin salir del editor
›

¿Qué es esto?

Soy Cristian Eslava y a veces hago webs para procrastinar yo y vosotros 😉.

Esta la hice en febrero de 2026 para facilitar el aprendizaje de mis alumnxs. Aprender desarrollo web practicando. La idea es que crezca semanalmente con nuevos temas, tests y retos.

Inspirado en MDN, en W3Schools, en Codepen, en el crack de Manz y en mil sitios de documentación sobre desarrollo web. Quería aportar además de bloques teóricos con ejemplos, la gamificación de los retos y el sistema de test que ya tenía en culTest .

Si te gustó, si no te gustó, si quieres saludarme, o invitarme a 🍻 no dudes en escribirme en cristianeslava@gmail.com .