Saltar a contenido

Capítulo 10: Publica tu sitio web con GitHub Pages

GitHub Pages convierte cualquier repositorio en un sitio web estático publicado en Internet sin necesidad de contratar un hosting adicional. La documentación oficial lo describe como un servicio de alojamiento de sitios estáticos que toma archivos HTML, CSS y JavaScript directamente desde un repositorio, opcionalmente los pasa por un proceso de construcción y publica un sitio accesible desde un dominio github.io o desde un dominio personalizado.[web:186][web:189]

En este capítulo vas a usar GitHub Pages para publicar el sitio web personal que has desarrollado desde el capítulo 2. Configurarás la publicación desde el repositorio, verás cómo cada Push actualiza el sitio y aprenderás a conectar un dominio propio y activar HTTPS.

10.1 ¿Qué es GitHub Pages?

GitHub Pages es un servicio de hosting estático integrado en GitHub. Según la documentación oficial, toma archivos HTML, CSS y JavaScript desde un repositorio, los publica y te permite servir un sitio desde https://<usuario>.github.io o desde un dominio personalizado.[web:186][web:189]

Cómo funciona

En esencia:

  • eliges un repositorio como origen del sitio;
  • defines una rama y carpeta como fuente de publicación (por ejemplo, main y /);[page:19]
  • GitHub Pages construye el sitio (por defecto con Jekyll si publicas desde una rama) o sirve directamente los archivos estáticos;
  • el sitio queda disponible en una URL pública.[web:186][web:189]

Para sitios simples como el proyecto del libro (HTML, CSS y JavaScript estáticos), GitHub Pages puede servir los archivos tal cual, sin necesidad de procesos de build complejos.

Qué tipo de proyectos puede alojar

GitHub Pages está pensado para:

  • sitios estáticos de portafolio y páginas personales;
  • documentación de proyectos;
  • demos front-end sin backend;
  • sitios generados por herramientas estáticas (Jekyll, Hugo, etc.), siempre que el resultado sean archivos estáticos.[web:186]

La documentación enfatiza que GitHub Pages no soporta lenguajes del lado del servidor como PHP, Ruby o Python.[page:19] Todo lo que sirvas debe ser contenido estático.

Diferencias con un hosting tradicional

En un hosting tradicional:

  • sueles subir archivos vía FTP o panel de control;
  • puedes ejecutar código del lado del servidor;
  • la infraestructura y configuración suelen ser tu responsabilidad.

En GitHub Pages:

  • subes el contenido como parte de tu repositorio Git;
  • cualquier Push al branch de publicación se convierte en una nueva versión del sitio;[page:19]
  • solo se sirven archivos estáticos;
  • GitHub se encarga de la infraestructura básica y HTTPS.[web:186][web:177]
Aspecto Hosting tradicional GitHub Pages
Despliegue Subida manual (FTP, panel) Push de Git al repositorio.[web:189]
Tipo de sitio Estático y dinámico Solo estático.[page:19]
Configuración Depende del proveedor Configuración desde Settings > Pages
HTTPS Puede requerir configuración manual GitHub lo proporciona automáticamente para github.io y soporta HTTPS en dominios personalizados.[web:177][web:180]

Ventajas para desarrolladores y estudiantes

  • publicar portafolios y proyectos sin coste adicional;
  • practicar un flujo real de despliegue basado en Git;
  • vincular repositorios a sitios visibles para docentes, reclutadores y colegas;
  • aprender a configurar dominios y HTTPS de forma controlada.[web:186][web:177]

Ejemplos reales:

  • sitios personales de desarrolladores (usuario.github.io);
  • documentación de librerías alojadas en repositorios;
  • páginas de cursos y materiales educativos.

[Ilustración: pantalla de un navegador mostrando un sitio estático simple publicado en usuario.github.io, con barra de direcciones visible y elementos del sitio web personal desarrollado en el libro]

Curiosidad

GitHub Pages se usa masivamente para documentación abierta y portafolios de desarrolladores. Es una de las formas más comunes de mostrar trabajos directamente desde repositorios Git.[web:186]

Breve conclusión: GitHub Pages es un hosting estático integrado con GitHub que publica tu sitio directamente desde un repositorio, ideal para portafolios, documentación y proyectos educativos como el sitio del libro.

10.2 Requisitos para publicar un sitio

Antes de habilitar GitHub Pages para el proyecto del libro, necesitas asegurarte de que la estructura del repositorio cumple con los requisitos mínimos.

Estructura mínima del proyecto

Según la guía “Creating a GitHub Pages site”, GitHub Pages busca un archivo de entrada (index.html, index.md o README.md) en la carpeta de publicación configurada.[page:19]

Para un sitio web como el del libro:

  • debes tener un index.html en la carpeta raíz del repositorio (o en /docs si usas esa carpeta como fuente);
  • puedes tener otros archivos como contacto.html, recursos.html, style.css, imágenes y scripts.

El requisito clave es que la carpeta de publicación tenga un archivo index que pueda ser servido como página principal.[page:19][web:187]

Archivos necesarios

Mínimo:

  • index.html: página de inicio.

Recomendados:

  • style.css: estilos globales;
  • otras páginas (contacto.html, recursos.html);
  • README.md: documentación del repositorio.

Repositorio público vs privado

La documentación indica que, para cuentas con GitHub Free, el repositorio debe ser público para usar GitHub Pages.[page:19] Organizaciones en GitHub Enterprise Cloud pueden gestionar visibilidad privada con controles adicionales, pero en el contexto del libro asumiremos repositorio público para simplificar.

Ramas compatibles y fuente de publicación

GitHub Pages permite configurar la fuente de publicación de dos maneras principales (sin entrar aún en GitHub Actions):[web:186][page:19]

  • cualquier rama del repositorio (por ejemplo, main);
  • carpeta raíz / o carpeta /docs de esa rama.

Esto se configura en Settings > Pages, donde eliges:

  • branch de origen;
  • carpeta de origen.

Para el proyecto del libro, la opción más simple suele ser:

  • branch: main;
  • carpeta de publicación: / (raíz del repositorio).

Condiciones actuales del servicio

La documentación de GitHub Pages también señala:[web:186]

  • los sitios se publican usando GitHub Actions por detrás, pero puedes ignorar eso si solo usas la configuración estándar;
  • los cambios pueden tardar hasta 10 minutos en reflejarse después de un Push;[page:19]
  • GitHub Pages no soporta código de servidor;
  • existen límites de tamaño y ancho de banda (1 GB de sitio publicado, 100 GB de tráfico mensual y hasta 10 builds por hora).[web:186]

Nota

Si tu sitio muestra un error 404 al publicarse, una causa frecuente es la ausencia de index.html en la carpeta de publicación o una configuración incorrecta de la fuente de Pages.[web:187][page:19]

Breve conclusión: para publicar el proyecto del libro en GitHub Pages necesitas un repositorio público con un index.html en la carpeta de publicación (raíz o /docs), y una configuración clara de rama y carpeta en Settings > Pages.

10.3 Publicando el proyecto

Con los requisitos cubiertos, es momento de activar GitHub Pages sobre el repositorio del sitio web personal.

Habilitar GitHub Pages

Según la documentación oficial, el flujo general para crear un sitio es:[page:19][web:189]

  1. Ir al repositorio del sitio en GitHub.
  2. Abrir Settings.
  3. En la sección "Code and automation" de la barra lateral, hacer clic en Pages.[page:19]
  4. Configurar el origen de publicación.

Seleccionar la rama y la carpeta

En la sección de GitHub Pages:

  • elige la rama de origen (por ejemplo, main);
  • elige la carpeta de publicación (/ para la raíz o /docs si tu sitio vive allí).[page:19][web:186]

Para el proyecto del libro, asume:

  • Branch: main;
  • Folder: /.

Esto indica que GitHub Pages debe tomar index.html y demás archivos directamente desde la raíz de main.

Esperar el despliegue

La documentación advierte que los cambios pueden tardar hasta 10 minutos en reflejarse en el sitio.[page:19][web:186]

Tras configurar la fuente:

  • GitHub lanza un workflow de publicación;
  • se construye el sitio (si corresponde);
  • se despliega en la URL asignada, por ejemplo:
https://tu-usuario.github.io/sitio-web-personal/

Verificar el sitio publicado

La guía de creación de sitios indica que puedes ver tu sitio desde Settings > Pages usando el botón Visit site.[page:19]

  1. En Settings > Pages, busca el apartado "GitHub Pages".
  2. Haz clic en Visit site.
  3. Se abrirá tu sitio en el navegador.

Si ves un error 404:

  • verifica que index.html existe en la carpeta configurada;
  • comprueba que la rama elegida tiene el contenido correcto;
  • espera unos minutos más por si el despliegue aún no termina.[web:187][page:19]
flowchart TD
    A[Repositorio con index.html] --> B[Settings > Pages]
    B --> C[Seleccionar rama main]
    C --> D[Seleccionar carpeta /]
    D --> E[GitHub construye y despliega]
    E --> F[Visit site: sitio publicado]

[Ilustración: captura descriptiva de la pestaña Settings de un repositorio, mostrando la sección Pages con opciones de rama, carpeta, botón Save y enlace Visit site, aplicada al proyecto del sitio web personal]

Error común

Configurar Pages para publicar desde /docs mientras tu index.html está en la raíz, o viceversa. Esto suele generar páginas 404 hasta ajustar la configuración.[web:187]

Breve conclusión: publicar el proyecto del libro con GitHub Pages consiste en configurar rama y carpeta de publicación desde Settings > Pages, esperar el despliegue y verificar que el sitio se sirva correctamente en la URL asignada.

10.4 Actualizando el sitio

Una vez configurado GitHub Pages, la actualización del sitio se integra al flujo normal de Git: cada Push a la rama de publicación dispara un nuevo build y despliegue.[web:186][web:189]

Ciclo completo de publicación

El flujo se convierte en:

Modificar

↓

Commit

↓

Push

↓

GitHub Pages

↓

Sitio actualizado

  1. Modificar: cambias archivos del sitio (index.html, recursos.html, style.css).
  2. Commit: registras los cambios en el historial local.
  3. Push: envías los commits a la rama de publicación (main).
  4. GitHub Pages: detecta cambios en la rama fuente y reconstruye el sitio.[web:186]
  5. Sitio actualizado: la nueva versión queda visible en la URL.
flowchart LR
    A[Editar archivos del sitio] --> B[git add / git commit]
    B --> C[git push origin main]
    C --> D[GitHub Pages reconstruye sitio]
    D --> E[Usuario ve sitio actualizado]

Ejemplos prácticos

  • agregas una nueva sección de recursos en recursos.html:

  • commit: Agregar sección de recursos avanzados;

  • push a main;

  • tras unos minutos, la sección aparece en el sitio publicado.

  • corriges un error ortográfico en la página de contacto:

  • commit: Corregir texto en formulario de contacto;

  • push;
  • el cambio se refleja sin necesidad de reconfigurar nada.

Qué sucede internamente

La documentación indica que GitHub Pages utiliza un flujo de publicación basado en GitHub Actions para construir y desplegar el sitio, o directamente publica archivos estáticos según la configuración.[page:19][web:186]

Para ti, el detalle interno no es crítico en este capítulo. Lo importante es saber que el repositorio y la rama de publicación son la única fuente de verdad: cualquier cambio en esa rama se refleja en el sitio público.

Buenas prácticas

Cada vez que publiques cambios importantes, revisa el sitio en su URL y asegúrate de que todo funcione antes de compartirlo con otras personas.[web:186]

Breve conclusión: con GitHub Pages configurado, tu sitio se convierte en una extensión directa de tu repositorio: hacer commit y push lleva tus cambios a producción de forma automática.

10.5 Dominios personalizados

GitHub Pages permite que tu sitio use un dominio personalizado en lugar de la URL por defecto usuario.github.io. La documentación oficial cubre tanto la configuración del archivo CNAME como los ajustes DNS necesarios.[web:176][web:175][web:179]

Ventajas de utilizar un dominio propio

  • da una imagen más profesional (por ejemplo, www.ejemplo-profesional.com);
  • facilita que estudiantes, colegas y reclutadores recuerden tu sitio;
  • desvincula la marca de GitHub en el URL, aunque siga usando su infraestructura.

Tipos de dominios compatibles

GitHub Docs señala que GitHub Pages funciona con:[web:179]

  • subdominios www (www.ejemplo.com);
  • subdominios personalizados (blog.ejemplo.com);
  • dominios apex (ejemplo.com).

Subdominios se suelen configurar con un registro CNAME, mientras que dominios apex se configuran con registros A, AAAA, ALIAS o ANAME apuntando a las IP correspondientes de GitHub Pages.[web:179][web:180]

Configuración del archivo CNAME

Para un subdominio como www.ejemplo-profesional.com:

  1. En el repositorio del sitio, crea un archivo CNAME en la raíz.
  2. Escribe dentro solo el dominio:
www.ejemplo-profesional.com

La documentación indica que este archivo informa a GitHub del dominio personalizado que debe asociarse al sitio.[web:176][web:175]

Configuración DNS

En el proveedor de dominios (ejemplo ficticio):

  • crea un registro CNAME para www apuntando a tu-usuario.github.io.[web:179][web:180]

Los IPs para dominios apex suelen ser valores específicos de GitHub Pages documentados en guías externas y en documentación.[web:180]

En este capítulo, usaremos un dominio de ejemplo, sin tocar dominios reales:

  • Dominio de ejemplo: www.misitio-educativo.com.

Configuración DNS típica:

  • CNAME www → tu-usuario.github.io.

Configurar el dominio en GitHub Pages

En Settings > Pages:

  1. En la sección de dominio personalizado, escribe www.misitio-educativo.com.
  2. Guarda la configuración.[web:176][web:175]

GitHub iniciará comprobaciones de DNS y, si todo está correcto, asociará el sitio al dominio personalizado.[web:177][web:175]

flowchart LR
    A[Repositorio con CNAME: www.misitio-educativo.com] --> B[DNS CNAME www -> usuario.github.io]
    B --> C[Settings > Pages: configurar dominio]
    C --> D[GitHub verifica DNS y asigna dominio]
    D --> E[Sitio accesible en www.misitio-educativo.com]

[Ilustración: pantalla de Settings > Pages mostrando campo de custom domain, botón Save, y un ejemplo de valor www.misitio-educativo.com, junto con referencia visual a registros DNS CNAME]

Error común

Configurar el dominio en GitHub Pages antes de que los registros DNS estén propagados, lo que puede retrasar la obtención del certificado y la vinculación correcta.[web:177][web:180]

Breve conclusión: un dominio personalizado se configura mediante un archivo CNAME en el repositorio, registros DNS apropiados (CNAME o A) y ajustes en Settings > Pages, permitiendo que tu sitio use una URL propia más profesional.

10.6 HTTPS

La documentación oficial indica que todos los sitios GitHub Pages, incluyendo los correctamente configurados con dominios personalizados, soportan HTTPS y pueden activar la opción de "Enforce HTTPS".[web:177][web:186][web:180]

Certificados SSL y activación automática

GitHub Pages utiliza certificados TLS (SSL) para cifrar el tráfico hacia el sitio:[web:177][web:180]

  • los sitios github.io creados después de junio de 2016 tienen HTTPS activado automáticamente;[web:177]
  • los dominios personalizados pueden obtener certificados automáticamente si los DNS están configurados correctamente y GitHub puede verificar el dominio.[web:177]

El proceso resumido:

  1. Configuras el dominio personalizado.
  2. GitHub verifica los registros DNS.
  3. Si todo está correcto, solicita un certificado a Let's Encrypt.[web:177]
  4. Cuando el certificado se emite, GitHub lo instala y habilita HTTPS.

Ventajas de HTTPS

  • protege la integridad del contenido (evita manipulaciones en tránsito);
  • protege la privacidad de usuarios (cifra comunicaciones);
  • mejora la percepción profesional del sitio y es requisito para muchas APIs modernas.

Activar y reforzar HTTPS

Para un sitio GitHub Pages:

  1. Ve a Settings > Pages.
  2. Busca la opción Enforce HTTPS.
  3. Actívala.[web:177]

Desde ese momento, las peticiones HTTP serán redirigidas automáticamente a HTTPS.[web:177]

Nota

Si tu sitio tiene contenido mixto (recursos cargados por http://), deberás actualizar las URLs a https:// para evitar advertencias de seguridad en el navegador.[web:177]

Breve conclusión: GitHub Pages gestiona certificados HTTPS de forma automática para github.io y dominios personalizados. Activar “Enforce HTTPS” asegura que todo el tráfico hacia tu sitio se maneje de forma cifrada y segura.

10.7 Limitaciones de GitHub Pages

Aunque GitHub Pages es muy útil, tiene límites claros que conviene conocer antes de decidir usarlo como hosting principal. La documentación oficial detalla varias restricciones y límites de uso.[web:186]

Sitios estáticos

GitHub Pages no soporta:[page:19]

  • PHP;
  • Ruby;
  • Python;
  • otros lenguajes de servidor.

Solo sirve archivos estáticos generados de antemano.

Límites de servicio

Según GitHub Docs, los límites actuales incluyen:[web:186]

  • repositorio fuente recomendado hasta 1 GB;
  • sitio publicado no mayor de 1 GB;
  • tiempo máximo de build de 10 minutos;
  • límite “suave” de 100 GB de ancho de banda por mes;
  • límite “suave” de 10 builds por hora (no aplica si usas GitHub Actions personalizados para publicar).[web:186]

Cuándo utilizar otro hosting

Debes considerar alternativas cuando:

  • necesitas backend (API propia, bases de datos, lógica de servidor);
  • tu sitio excede los límites de tamaño o tráfico;
  • tu proyecto es principalmente un SaaS o sitio comercial, algo que GitHub Pages no está pensado para hospedar.[web:186]

Proyectos recomendados

GitHub Pages es ideal para:

  • portafolios de desarrolladores;
  • páginas de cursos y materiales educativos;
  • documentación de librerías y proyectos;
  • demos estáticas del sitio web personal del libro.
Característica GitHub Pages
Tipo de contenido Sitios estáticos (HTML, CSS, JS).[web:186]
Tamaño recomendado Hasta 1 GB de sitio publicado
Tráfico 100 GB/mes (soft limit)
Builds 10 builds/hora (soft limit)
Backend No soportado

¿Sabías que...?

GitHub mismo sugiere, en caso de superar los límites, considerar poner un CDN delante del sitio o migrar a un hosting más adecuado para cargas muy altas.[web:186]

Breve conclusión: GitHub Pages está optimizado para sitios estáticos de tamaño moderado, con límites razonables de tráfico y build. Es perfecto para el proyecto del libro, pero no sustituye a un hosting completo para aplicaciones con backend.

10.8 Buenas prácticas

Para aprovechar GitHub Pages al máximo en tu sitio del libro, conviene seguir algunas recomendaciones de organización y despliegue.

Organización del proyecto

  • Mantén una estructura clara de carpetas: css, js, images, etc.
  • Usa nombres significativos y consistentes (index.html, contacto.html, recursos.html).
  • Evita archivos temporales o de desarrollo innecesarios en la carpeta de publicación.

Estructura de archivos

  • Asegúrate de que la página principal sea index.html en la carpeta fuente.
  • Incluye un 404.html si quieres una página de error personalizada (GitHub Pages la utiliza automáticamente para errores 404).[web:186]
  • Si usas generadores estáticos, recuerda incluir .nojekyll si no quieres que Jekyll procese tu sitio.[page:19]

Despliegues frecuentes y mantenimiento

  • Haz commits pequeños y descriptivos.
  • Publica cambios con regularidad, verificando el resultado en la URL.
  • Mantén actualizado el contenido para reflejar tu progreso profesional o académico.
Recomendación Beneficio
index.html bien estructurado Evita errores 404 y mejora la experiencia
Carpeta raíz limpia Facilita publicación y mantenimiento
Commits frecuentes Mantiene el sitio en sincronía con el repositorio
Uso de tags para versiones clave Permite volver a estados estables del sitio

[Ilustración: vista de un proyecto ordenado en GitHub con carpetas css, js, images y archivos index.html, contacto.html, recursos.html, resaltando buena organización de cara a GitHub Pages]

Buenas prácticas

Trata tu sitio en GitHub Pages como un proyecto vivo: cada cambio pasa por Git, se publica y se revisa. Esa disciplina refleja el flujo profesional de desarrollo y despliegue.

Breve conclusión: una estructura limpia, un index.html claro, despliegues frecuentes y uso de versiones estables convierten GitHub Pages en una herramienta sólida para tu presencia técnica en la web.

Práctica guiada

En esta práctica vas a publicar el sitio del libro con GitHub Pages, actualizarlo, configurar un dominio de ejemplo y activar HTTPS.

Paso 1: preparar el proyecto

  1. Verifica que index.html exista en la raíz del repositorio.
  2. Confirma que main es la rama principal y que el sitio funciona localmente.

Paso 2: habilitar GitHub Pages y publicar

  1. Abre el repositorio en GitHub.
  2. Ve a Settings.
  3. En la barra lateral, abre Pages.[page:19]

  4. Configura:

  5. Branch: main;

  6. Folder: /.

  7. Guarda y espera unos minutos.

  8. Usa Visit site para abrir el sitio publicado.[page:19]

Paso 3: acceder al sitio desde Internet

  1. Copia la URL mostrada (por ejemplo, https://tu-usuario.github.io/sitio-web-personal/).
  2. Abre esa URL en un navegador externo.
  3. Comprueba que el sitio se ve correctamente.

Paso 4: modificar el proyecto y publicar nuevas versiones

  1. Edita contenido de index.html o recursos.html.
  2. Haz commit y push a main.
  3. Espera unos minutos.
  4. Recarga el sitio y verifica que los cambios se reflejan.

Paso 5: configurar un dominio de ejemplo

  1. Imagina que posees www.misitio-educativo.com.
  2. Crea un archivo CNAME en la raíz del repositorio con:
www.misitio-educativo.com

  1. En el proveedor DNS, configurarías (ejemplo teórico):

  2. CNAME www → tu-usuario.github.io.[web:179][web:176]

  3. En Settings > Pages, añade www.misitio-educativo.com como dominio personalizado.[web:176]

  4. Espera a que la verificación DNS y la obtención del certificado se completen.[web:177]

Paso 6: activar HTTPS

  1. En Settings > Pages, marca Enforce HTTPS.[web:177]
  2. Verifica que el sitio responde en https://www.misitio-educativo.com (ejemplo) y que las peticiones HTTP se redirigen.[web:177][web:180]

Paso 7: verificar errores comunes

  • Si ves 404:

  • confirma que index.html está en la carpeta de publicación;

  • revisa Settings > Pages para asegurar que la fuente está bien configurada.[web:187]

  • Si el dominio de ejemplo no responde:

  • revisa configuraciones DNS y asegúrate de que la propagación haya terminado;

  • verifica el archivo CNAME y el dominio en Settings > Pages.

Diagrama de la práctica

flowchart TD
    A[Preparar proyecto con index.html] --> B[Configurar Pages en Settings]
    B --> C[Sitio publicado en usuario.github.io]
    C --> D[Modificar y hacer push]
    D --> E[Sitio se actualiza]
    E --> F[Configurar dominio personalizado]
    F --> G[Activar HTTPS]
    G --> H[Verificar sitio desde Internet]

[Ilustración: secuencia visual que muestra primero la configuración de Pages, luego la vista del sitio en usuario.github.io y finalmente el mismo sitio servido desde un dominio personalizado con candado de HTTPS en la barra del navegador]

Consejo

Documenta la URL de tu sitio GitHub Pages en el README del repositorio. Así cualquiera que visite tu código podrá encontrar fácilmente la versión publicada.[web:186]

Breve conclusión: la práctica guiada te lleva desde un proyecto local hasta un sitio publicado y seguro en Internet usando GitHub Pages, con dominio personalizado y HTTPS, todo controlado a través de Git y GitHub.

Cierre del capítulo

En este capítulo transformaste el proyecto del libro en un sitio web real publicado en Internet. Aprendiste qué es GitHub Pages, qué requisitos tiene y cómo configurar rama y carpeta de publicación para el repositorio del sitio.[web:186][page:19]

También viste cómo el flujo de Git (commit y push) se convierte en un flujo de despliegue automático, cómo añadir un dominio personalizado mediante archivo CNAME y ajustes DNS, y cómo activar HTTPS para proteger el tráfico hacia tu sitio.[web:176][web:175][web:177][web:180] Con estas herramientas, tu trabajo con Git deja de ser solo local y se convierte en presencia visible en la web, alineada con prácticas profesionales.

Bibliografía