Eine Gatsby-Website mit Travis CI auf GitHub Pages bereitstellen

Vor Kurzem habe ich an einer einfachen statischen Website für ein Open-Source-Projekt gearbeitet und Gatsby zusammen mit einem der Theme-Starter ausprobiert. Um die Webseiten bereitzustellen, habe ich beschlossen, meine mit Gatsby generierte statische Website auf GitHub Pages zu hosten, wo auch der Quellcode liegt. So ist alles schön miteinander verknüpft.

Mit GitHub Pages gibt es zwei Möglichkeiten, die Website zu hosten und bereitzustellen:

1.  einen eigenen Branch mit dem Namen gh-pages.

2. einen anderen Branch verwenden, zum Beispiel master, und den gesamten Website-Code in einem docs/-Verzeichnis ablegen.

Für mein Projekt habe ich mich für die zweite Möglichkeit entschieden: Ich habe den gesamten Quellcode der Website im docs/-Verzeichnis des Branches master abgelegt und die Website dann in gh-pages bereitgestellt.

Auf GitHub Pages bereitstellen

Gatsby generiert den Code der statischen Website im Verzeichnis public/, der auf GitHub Pages übertragen werden muss, damit die Website bereitgestellt werden kann. Um den Code von Travis CI aus in das Remote-Repository zu übertragen und die nötigen Git-Schritte auszuführen, verwenden wir das npm-Modul gh-pages.

Sie können das gh-pages-Modul auch installieren, um die Bereitstellung in Ihrer lokalen Entwicklungsumgebung zu testen. Das ist jedoch nicht zwingend erforderlich.

Schritt 1: GitHub-Token abrufen

Um Änderungen vom CI-System – in unserem Fall Travis CI – an GitHub Pages zu übertragen, müssen Sie sich authentifizieren. Dafür empfiehlt es sich, GitHub-Entwickler-Token zu verwenden, statt Ihren Kontonamen und Ihr Passwort anzugeben.

Rufen Sie in GitHub die Kontoeinstellungen auf und wählen Sie Developer settings -> Personal access tokens. Erstellen Sie ein neues Token mit Berechtigungen für den Repository-Zugriff.

Fügen Sie in der Travis-Konfiguration für das Repository eine neue geheime Umgebungsvariable mit dem Namen GH_TOKEN und dem von GitHub erhaltenen Token als Wert hinzu. Achten Sie darauf, die Einstellung „In Build-Protokollen anzeigen“ NICHT zu aktivieren, damit das Token geheim bleibt. Andernfalls können andere Änderungen in Ihr Repository übertragen.

Schritt 2: Deploy-Skript hinzufügen

Ergänzen Sie die package.json des Gatsby-Projekts um ein deploy-Skript, das gh-pages mit zwei wichtigen Befehlsargumenten aufruft:

1. -d public – gibt das Verzeichnis an, in dem sich die erstellten Dateien befinden und das als Quelle auf GitHub Pages übertragen wird.

2. -r URL – die URL des GitHub-Repositorys. Sie enthält ein GitHub-Token, mit dem Änderungen in den Branch gh-pages übertragen werden können, und hat folgendes Format: https://$GH_TOKEN@github.com/<github username>/<github repository name>.git

Hier ein Beispiel:

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

Schritt 3: .travis.yml aktualisieren

Die folgende Konfiguration für .travis.yml dient als Vorlage:

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

Sehen wir uns die wichtigsten Bestandteile für die Bereitstellung der Gatsby-Website von Travis auf GitHub Pages an:

1. Mit before_script wird die Gatsby-CLI installiert, damit der Befehl gatsby im Skript des Projekts zum Erstellen der Gatsby-Website verwendet werden kann.

2. deploy wird nur ausgeführt, wenn der Build im Branch master läuft. In diesem Fall wird das script gestartet. Das script enthält Anweisungen, um die im Verzeichnis docs/ befindliche Gatsby-Website bereitzustellen. In diesem Verzeichnis müssen alle Website-Abhängigkeiten installiert und das Deploy-Skript ausgeführt werden, das im vorherigen Schritt festgelegt wurde.

Zusammenfassung

Mit diesem Tutorial können Sie Ihre Website jetzt veröffentlichen und mit uns teilen!

Wenn Sie CircleCI oder andere Tools verwenden, sind der Workflow und die allgemeinen Richtlinien nahezu identisch. Ausnahmen bilden die spezifischen Einstellungen in der Deployment-Datei von CircleCI und die Umgebungsvariablen. Im Sinne von Open Source habe ich einen Dokumentations-Pull-Request zum offiziellen Gatsby-Repository beigetragen, der den gesamten Prozess beschreibt und es künftigen Gatsby-Nutzern erleichtert.