Implementar un sitio de Gatsby en GitHub Pages desde Travis CI

Hace poco trabajé en un sitio web estático sencillo para un proyecto de código abierto que tengo y probé Gatsby junto con uno de los temas iniciales. Para publicar las páginas web, decidí alojar el sitio estático generado con Gatsby en GitHub Pages, donde también alojo el código fuente, para que todo quede bien integrado.

Con GitHub Pages, hay dos opciones para alojar y publicar el sitio web:

1.  una rama dedicada llamada gh-pages.

2. usar otra rama, por ejemplo, master, y colocar todo el código del sitio web en un directorio docs/.

Para mi proyecto, elegí esta última opción y coloqué todo el código fuente del sitio web en el directorio docs/ de la rama master y luego lo implementé en gh-pages.

Implementar en GitHub Pages

Gatsby genera el código del sitio web estático en el directorio public/, que debe enviarse a GitHub Pages para publicarlo. Para enviar el código al repositorio remoto desde Travis CI y encargarnos de toda la magia de Git, usamos el módulo de npm gh-pages.

También puedes instalar el módulo gh-pages para probar e implementar desde tu entorno de desarrollo local, pero no es obligatorio.

Paso 1: obtener un token de GitHub

Para enviar cambios desde el sistema de CI, en nuestro caso Travis CI, a GitHub Pages, debes autenticarte. Una forma recomendada de hacerlo es usar tokens para desarrolladores de GitHub, en lugar de proporcionar el nombre de usuario y la contraseña de tu cuenta.

En GitHub, ve a la configuración de tu cuenta -> Developer settings -> Personal access tokens y crea un token nuevo que otorgue permisos de acceso al repositorio.

En la configuración de Travis, agrega una nueva variable de entorno secreta para el repositorio, llamada GH_TOKEN, con el valor del token obtenido de GitHub. Asegúrate de NO activar la opción display in build logs, ya que es mejor mantener el token en secreto. De lo contrario, otras personas podrán enviar cambios a tu repositorio.

Paso 2: crear el script de implementación

Actualiza el archivo package.json del proyecto de Gatsby para incluir también un script de ejecución deploy que invoque gh-pages con dos argumentos de comando importantes:

1. -d public - especifica el directorio donde se encuentran los archivos compilados y que se enviarán a GitHub Pages como fuente

2. -r URL - la URL del repositorio de GitHub, incluido un token de GitHub para poder enviar cambios a la rama gh-pages, con el formato https://$GH_TOKEN@github.com/<github username>/<github repository name>.git

Aquí tienes un ejemplo:

"scripts": {
  "deploy": "gatsby build --prefix-paths && gh-pages -d public -r https://$GH_TOKEN@github.com/lirantal/dockly.git"
}

Paso 3: actualizar .travis.yml

La siguiente configuración de .travis.yml sirve como referencia:

language: node_js
before_script:
  - npm install -g gatsby
node_js:
  - "10"
deploy:
  provider: script
  script: cd docs/ && yarn install && yarn run deploy
  skip_cleanup: true
  on:
    branch: master

Veamos los elementos importantes para implementar el sitio de Gatsby desde Travis en GitHub Pages:

1. before_script se usa para instalar Gatsby CLI, de modo que se pueda usar el comando gatsby en el script de ejecución del proyecto para compilar el sitio web de Gatsby.

2. deploy se ejecuta solo cuando la compilación se realiza en la rama master; en ese caso, ejecuta el script. Aquí, script es un conjunto de instrucciones para implementar el sitio de Gatsby ubicado en el directorio docs/. En este directorio, hay que instalar todas las dependencias del sitio web y ejecutar el script de implementación, tal como se configuró en el paso anterior.

Resumen

Después de seguir este tutorial, ya tienes todo listo para compartir tu sitio web con el mundo y con nosotros.

Si usas CircleCI u otras herramientas, el flujo de trabajo y las pautas generales son casi idénticos, excepto por los detalles del archivo de implementación y la configuración de variables de entorno de CircleCI. Como parte del espíritu del código abierto, contribuí un Pull Request de documentación al repositorio oficial de Gatsby que documenta todo este proceso, para que quienes usen Gatsby en el futuro puedan hacerlo más fácilmente.