GitHub Pages: alojamiento gratuito de tu sitio web y cómo publicarlo paso a paso

Qué es GitHub Pages

GitHub Pages es un alojamiento gratuito de sitios estáticos integrado en GitHub. Guardas los archivos del sitio en un repositorio Git normal, y GitHub los sirve por HTTPS. Cada nuevo git push a la rama indicada actualiza el sitio, así que no necesitas FTP, panel de hosting ni subir archivos a mano.

En las búsquedas en español el servicio aparece con distintos nombres: «github pages», «github pagina», «github pages gratis», a veces simplemente «hosting de github». Y también se busca «git pages qué es»; pero el nombre correcto es GitHub Pages: es una función de la plataforma GitHub, no del propio Git. Git no publica nada, solo guarda el historial de los cambios.

Lo más habitual es publicar en GitHub Pages documentación de proyectos, páginas personales y portafolios, blogs, landings y proyectos de demostración de front-end en React, Vue o Svelte ya compilados.

GitHub Pages es alojamiento de contenido estático

La palabra clave es estático. GitHub Pages entrega al navegador archivos ya preparados: HTML, CSS, JavaScript, imágenes, fuentes, JSON. No ejecuta código en el servidor: PHP, Python o Node.js del lado del servidor y las bases de datos no funcionan aquí. Si el sitio necesita registro de usuarios, carrito de compra o un panel de administración con base de datos, hace falta un hosting tradicional o una plataforma en la nube.

El JavaScript sí funciona en el navegador como siempre. Una aplicación de una sola página puede consultar APIs externas, los formularios pueden enviarse a través de servicios de terceros y la búsqueda en el sitio puede hacerse en el cliente.

Qué tipos de sitios hay en GitHub Pages

GitHub Pages tiene tres tipos de sitio, y el tipo determina la dirección.

Por cuenta solo puede haber un sitio de usuario o de organización, pero de proyecto puede haber tantos como repositorios, uno por repositorio. El nombre del repositorio del sitio personal debe coincidir exactamente con tu usuario de GitHub: si tu usuario es ivan-petrov, el repositorio se llama ivan-petrov.github.io.

Para repositorios públicos, Pages está disponible en el plan gratuito. Publicar un sitio desde un repositorio privado requiere un plan de pago de GitHub; en cualquier caso, el sitio publicado es visible para todo el mundo en internet.

Cómo publicar un sitio en GitHub Pages paso a paso

Veamos la vía más sencilla: archivos HTML listos, publicados desde una rama. Necesitas una cuenta de GitHub y Git instalado.

Paso 1. Crea el repositorio

En GitHub crea un repositorio público nuevo. Para un sitio personal, llámalo username.github.io; para el sitio de un proyecto, el nombre es libre. Después clónalo y añade la página principal:

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Hola, GitHub Pages</h1>" > index.html

La página principal se llama obligatoriamente index.html (o index.md, o README.md: GitHub también los convierte en portada). Las mayúsculas importan: Index.html no sirve.

Paso 2. Sube los archivos a GitHub

git add index.html
git commit -m "Primera página del sitio"
git push origin main

Si es la primera vez que envías cambios y Git pide usuario y contraseña, usa un token de acceso personal o el inicio de sesión en el navegador: la contraseña normal de la cuenta de GitHub no sirve para git push por HTTPS.

Paso 3. Activa Pages en la configuración

Abre el repositorio en GitHub, entra en Settings y en el menú lateral elige Pages. En el bloque Build and deployment, en el campo Source, selecciona Deploy from a branch. Debajo indica la rama (normalmente main) y la carpeta: la raíz / (root) o /docs. Pulsa Save.

La carpeta /docs es cómoda cuando el repositorio contiene el código del proyecto y, junto a él, un sitio con la documentación en un directorio aparte.

Paso 4. Espera a la publicación

La publicación tarda de unos segundos a unos minutos; GitHub avisa de que la primera puede tardar hasta 10 minutos. El progreso se ve en la pestaña Actions: aparecerá un proceso llamado pages build and deployment. Cuando termine con una marca verde, en Settings → Pages aparecerá la dirección del sitio.

A partir de ahí, todo es sencillo: editas los archivos, haces commit y git push, y el sitio se actualiza solo.

Publicación con GitHub Actions

La publicación desde una rama sirve cuando el repositorio contiene archivos ya preparados. Si el sitio hay que compilarlo antes —por ejemplo, es una aplicación con Vite, React o un generador como Hugo—, es mejor la fuente GitHub Actions. En Settings → Pages, en Source, elige GitHub Actions, y GitHub ofrece plantillas de workflow listas para usar.

Un workflow mínimo para publicar los archivos estáticos de la carpeta dist tras la compilación tiene este aspecto:

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

El archivo se guarda en .github/workflows/pages.yml. Tras el git push, Actions instala las dependencias, compila el proyecto y publica el contenido de dist. La ventaja de este método es que el repositorio guarda solo el código fuente y los archivos compilados no ensucian el historial de commits.

Una trampa frecuente en los sitios de proyecto son las rutas. El sitio se abre en /nombre-del-repositorio/, pero el compilador por defecto enlaza los recursos desde la raíz /. Como resultado, la página carga sin estilos ni scripts. Se soluciona configurando la ruta base: en Vite, el parámetro base: '/nombre-del-repositorio/'; en otros compiladores, una opción equivalente.

Jekyll y generadores de sitios estáticos

Al publicar desde una rama, GitHub procesa los archivos por defecto con Jekyll, un generador de sitios estáticos escrito en Ruby. Por eso puedes escribir las páginas en Markdown, usar temas y plantillas, y GitHub las convertirá en HTML. Para un blog o una documentación es cómodo: escribes archivos .md y el diseño lo aporta el tema.

Efecto secundario: Jekyll ignora los archivos y carpetas cuyo nombre empieza por guion bajo, por ejemplo _next o _assets. Si el sitio está compilado con otra herramienta y esas carpetas son necesarias, pon en la raíz un archivo vacío .nojekyll:

touch .nojekyll
git add .nojekyll
git commit -m "Desactivar Jekyll"
git push

Otros generadores —Hugo, Astro, Eleventy, MkDocs, Docusaurus— funcionan mediante GitHub Actions: el workflow compila y publica la carpeta resultante. GitHub Pages en sí no conoce estas herramientas; le basta con los archivos finales.

Cómo conectar tu dominio a GitHub Pages

La dirección username.github.io sirve para proyectos de estudio, pero para un portafolio o un proyecto es mejor un dominio propio. La conexión se hace en dos sentidos: en el registrador del dominio y en la configuración del repositorio.

Configuración DNS

Para un subdominio como www.example.com o blog.example.com, crea un registro CNAME que apunte a username.github.io. Para el dominio raíz example.com, crea registros A con las direcciones IP de GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

La lista actual de direcciones, incluido IPv6 para los registros AAAA, está en la documentación de GitHub; compruébala antes de configurar. Conviene configurar tanto el dominio raíz como www: así GitHub redirige una dirección a la otra.

Configuración en el repositorio

En Settings → Pages escribe el dominio en el campo Custom domain y guarda. Al publicar desde una rama, GitHub crea en el repositorio un archivo CNAME con el nombre del dominio. Al publicar mediante Actions no hace falta el archivo CNAME: el dominio se guarda en la configuración.

GitHub recomienda verificar el dominio en la configuración de la cuenta (sección Pages de los ajustes del perfil). Esto protege frente a que alguien más vincule tu dominio a su repositorio mientras el DNS apunta a GitHub. Los cambios de DNS tardan hasta un día en propagarse; si el dominio no funciona de inmediato, espera.

HTTPS en GitHub Pages

Para las direcciones *.github.io el HTTPS está siempre activado. Para tu propio dominio, GitHub emite por sí mismo un certificado de Let's Encrypt cuando el DNS está bien configurado. Después aparece en Settings → Pages la casilla Enforce HTTPS: actívala para que todas las peticiones por HTTP se redirijan a HTTPS.

Si la casilla está inactiva, el certificado aún no se ha emitido: revisa los registros DNS y espera. A veces ayuda quitar el dominio del campo Custom domain y volver a añadirlo, lo que lanza una nueva emisión del certificado. Comprueba también que el sitio no carga imágenes ni scripts por http://: el navegador bloqueará esos recursos como contenido mixto.

Límites de GitHub Pages

El alojamiento es gratuito, pero tiene sus límites. Están descritos en la documentación de GitHub, y para la mayoría de los sitios personales y de estudio son más que suficientes.

Además de los límites técnicos hay normas de uso: GitHub Pages no está pensado para servicios comerciales como tiendas en línea o SaaS, ni para distribuir archivos grandes. Para un portafolio, documentación, un blog o la landing de un proyecto, sí está permitido.

Otra limitación es la ausencia de configuración del servidor. No hay redirecciones propias, cabeceras de respuesta ni reglas tipo .htaccess. Solo puedes poner una página 404.html en la raíz: GitHub la mostrará para las direcciones que no existen.

Problemas habituales y cómo resolverlos

Error 404 en GitHub Pages

La causa más común es que no existe el archivo index.html en la carpeta elegida como fuente. Comprueba que has elegido la rama y la carpeta correctas (/ (root) o /docs) y que el archivo se llama exactamente index.html en minúsculas. La segunda causa es que el sitio aún no se ha publicado: mira la pestaña Actions y espera a que termine la compilación.

Si aparece un 404 en las páginas internas de una aplicación de una sola página al recargar, es un problema de enrutamiento: el servidor no conoce la dirección /about porque ese archivo no existe. Las soluciones alternativas son el enrutamiento por hash (/#/about) o una copia de index.html con el nombre 404.html.

El sitio no se actualiza

Primero asegúrate de que los cambios llegaron a GitHub: ejecuta git status y git log origin/main --oneline -3. Después abre la pestaña Actions: si la compilación falló, verás una cruz roja y un registro con el error, por ejemplo una sintaxis incorrecta en un archivo de Jekyll o un fallo en el workflow.

Si la compilación terminó bien y en el navegador ves la versión antigua, la culpa es de la caché. GitHub Pages guarda los archivos en caché durante unos minutos, y además el navegador guarda su propia copia. Recarga la página limpiando la caché (Ctrl+F5 o Cmd+Shift+R) o ábrela en una ventana privada.

No cargan los estilos ni las imágenes

Casi siempre son rutas incorrectas. En un sitio de proyecto, el enlace /style.css apunta a la raíz de username.github.io, no a la carpeta del repositorio. Usa rutas relativas (style.css, ./img/logo.png) o define la ruta base en el compilador. Revisa también las mayúsculas: los servidores de GitHub distinguen Logo.PNG de logo.png, aunque en Windows en local todo funcionara.

Faltan carpetas que empiezan por guion bajo

Es Jekyll: no publica directorios como _app. Añade a la raíz el archivo .nojekyll o pasa a publicar mediante GitHub Actions.

Resumen

GitHub Pages es la forma más rápida de publicar gratis un sitio estático: un repositorio, un archivo index.html y la fuente en Settings → Pages. En un par de minutos el sitio está abierto en username.github.io. Para sitios que requieren compilación, usa GitHub Actions; para tu propio dominio, los registros DNS y la casilla Enforce HTTPS. Ten en cuenta los límites: solo estática, sin código de servidor y con restricciones de tamaño y tráfico. El trabajo con GitHub, el envío de cambios y la automatización se explican con práctica en el curso de Git.