Skip to content

GitHub Pages

GitHub Pages es una solución práctica para publicar webs basadas únicamente en tecnologías cliente (HTML, CSS y JavaScript). En este documento explicaremos distintas formas de crear repositorios en GitHub y activar GitHub Pages en ellos.

1. Creación de webs simples

En primer lugar, veremos cómo subir una web para que se publique sin más, desde la carpeta raíz del repositorio. Por ejemplo, podemos tener un fichero index.html en nuestra carpeta raíz del repositorio, y subcarpetas adicionales para CSS o imágenes si queremos. Subimos todo el contenido al repositorio, y vamos a los Settings del mismo. En el menú izquierdo veremos una sección llamada Pages, donde debemos configurar desde qué rama se publican los cambios (podemos elegir la rama principal, main).

Desde este momento, cada vez que hagamos commit y push de nuestros cambios locales al repositorio, podremos acceder a nuestra web. El nombre de dominio coincide con nuestro usuario de GitHub seguido de la extensión .github.io y el nombre de nuestro repositorio. Por ejemplo, si el usuario es usu123 y el repositorio es prueba, la URL completa de acceso sería usu123.github.io/prueba.

2. Creación de webs desplegadas en carpetas

Si utilizamos algún framework de diseño como Tailwind o similar, es posible que la web se empaquete en una subcarpeta como dist. En este caso conviene configurar el repositorio para que almacene todo el código fuente de nuestro proyecto, pero para que GitHub Pages se fije en la subcarpeta concreta donde se ha desplegado o empaquetado la web.

Por ejemplo, imaginemos que tenemos un proyecto Tailwind. Estos son los pasos a seguir para configurarlo adecuadamente en GitHub Pages.

Advertencia

Estos pasos deberemos seguirlos sólo la primera vez que configuremos el proyecto con Vite + GitHub Pages. El resto de veces que hagamos commit y push ya se aplicará la configuración que hayamos elegido (aunque puede que tarde unos segundos/minutos tras el push en activar los cambios en la web de GitHub Pages).

Advertencia

Recuerda añadir el fichero .gitignore del proyecto Tailwind a tu repositorio, para excluir las carpetas node_modules, dist y otros recursos en la subida a GitHub.

1. Configurar la ruta base Vite

Por defecto, Vite asume que la web se publicará en la raíz de un dominio (ej: https://miweb.com). Como en GitHub Pages se publicará en https://usuario.github.io/nombre-del-repositorio/, debemos avisar a Vite. Para ello abrimos el fichero de configuración de Vite vite.config.ts y añadimos la propiedad base con el nombre de nuestro repositorio:

import { defineConfig } from 'vite'

export default defineConfig({
  base: '/nombre-del-repositorio/', 
  // ... resto de la configuración
})

2. Crear automatismo de despliegue con GitHub Actions

Vamos a crear un "robot" que, cada vez que hagamos un git push empaquete la web y la suba a una rama especial de publicación. Para ello:

  1. En la carpeta raíz del proyeco, creamos una carpeta llamada .github (con el punto delante).
  2. Dentro de esa, creamos otra llamada workflows.
  3. Dentro de workflows, creamos un archivo deploy.yml con este código:
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ] # Se activa al subir cambios a la rama main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4

      - name: Install and Build 🔧
        run: |
          npm install
          npm run build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: dist # Sube solo el contenido de la carpeta dist
          branch: gh-pages # Lo publica en esta rama separada

3. Dar permisos de escritura a GitHub Actions

Por defecto GitHub Actions sólo tiene permisos para leer el repositorio, pero no para hacer cambios en él. En este caso le estamos pidiendo que vuelque los cambios de la web en la rama gh-pages, así que tenemos que habilitar estos permisos. Vamos a las Settings de nuestro repositorio, y buscamos Actions > General en el panel izquierdo. Accedemos a la sección que pone Workflow permissions y marcamos la casilla de lectura y escritura:

4. Subir los cambios y activación final

Guardamos y subimos los cambios (commit y push, como lo hagamos normalmente) y esperamos un minuto para que el robot que hemos configurado haga su trabajo. Después vamos al repositorio GitHub y vamos a Settings > Pages. En el apartado Build and deployment elegimos Branch y elegimos la rama gh-pages que hemos configurado previamente en el fichero deploy.yml. Hacemos clic en Save para terminar.

Futuros cambios

A partir de aquí, cada cambio que hagamos en la web (nuevo contenido HTML, estilos, CSS, imágenes, etc) se subirá y desplegará automáticamente al hacer commit y push.