DatoCMS zusammen mit einer statisch generierte Webseite (SSG) verwenden

Inhalt ist nicht statisch

Als wir unsere Webseite neovo.ch erstellt haben, war es unser Ziel die "Feuerwerk"-Animation (siehe Bild oben) zu sehen, nachdem Google Lighthouse darauf ausgeführt wurde.

Um dies zu erreichen, muss die Webseite verschiedene Performance- und UX-relevante Punkte erfüllen. Einer der wichtigsten Faktoren dabei, ist aber die Zeit, die benötigt wird, die Webseite zu laden. Und was ist die schnellstmögliche Implementation einer Webseite? Natürlich, wenn diese während des Deployments zu statischem HTML vor-generiert wird. Dadurch sind beim Aufrufen einer Seite keine Requests an ein Backend mehr nötig, um diese zu rendern.

Da die Inhalte auf unserer Webseite (sowie vermutlich der meisten Webseiten im Internet) in einem CMS gepflegt werden, muss man die Möglichkeit haben, diese neu zu generieren, sobald sich diese ändern.

DatoCMS ❤️ SSG

DatoCMS stellt mit den sogenannten Build triggers ein Feature bereit, welches genau dafür gedacht ist. Diese Build triggers können in den globalen "Projekteinstellungen" von DatoCMS konfiguriert werden. Mit ihnen erhalten Content-Editoren die Möglichkeit manuell einen Build der Webseite anzustossen, nachdem sie deren Inhalt geändert haben.

Ein Build trigger kann sogar so konfiguriert werden, dass er automatisch ausgeführt wird, sobald eine geplante Veröffentlichung (oder Unveröffentlichung) eines Inhaltes geschehen ist.

Den Build Trigger konfigurieren

DatoCMS verfügt bereits über einige vorkonfigurierte Build Triggers für CI-Tools wie Gitlab, Travis und CircleCI sowie für CDN-Hosting Plattformen wie Netlify und Vercel. Wenn deine Webseite nicht über eine dieser Plattformen deployt oder darauf gehostet wird, hast du die Möglichkeit einen Custom build trigger zu definieren. Um es einfach zu sagen, ist ein Build trigger nichts anders als ein manuell ausgeführter POST-Request auf eine definierte URL (mit, wenn nötig, vorkonfiguriertem Inhalt).

Für das Hosting des Repositories unserer Webseite neovo.ch verwenden wir Forgejo. Dabei handelt es sich um eine selbst-gehostete Alternative zu GitHub. Die CI/CD-Lösung davon implementiert dasselbe API wie die GitHub Actions, was soviel bedeutet, dass die hier beschriebene Lösung auch für Webseiten funktioniert, die auf GitHub gehostet werden.

Da es keinen vorkonfigurierten Build Trigger für GitHub Actions gibt, müssen wir einen Custom Build Trigger erstellen. Dies geschieht indem man während der Erstellung eines neuen Build triggers auf "Custom webhook" klickt. Folgende Angaben müssen dafür gemacht werden:

• Build Trigger Name: Gib dem Trigger eine sinnvolle Bezeichnung. Diese hilft den Content-Editoren, den richtigen Trigger zu finden, wenn sie ein Deployment starten möchten. (beispielsweise wenn deine Webseite eine Produktions- sowie eine Staging-Umgebung hat).

• Website frontend URL: Die URL, über welche die deployte Webseite aufgerufen werden kann.

• Automatically trigger a build on scheduled publications/un-publications: Aktiviere diese Option, wenn du einen Build auslösen möchtest, sobald eine geplante Veröffentlichung oder Nichtveröffentlichung des Inhalts erfolgt.

• Trigger URL: Der Trigger sendet eine POST-Anfrage an diese URL. (Wie diese URL aussieht, erfährst du weiter unten unter "Einrichten des Webhooks auf deiner CI/CD")

• Custom headers: Hier kannst du Custom-Headers, welche für den Request nötig sind, definieren (bspw. zur Authentifizierung).

• JSON payload: Hier kannst du Inhalte definieren, welche dann während dem Build und Deployment verwenden werden können (bspw. um das Ziel-Environment zu definieren).

Einrichten des Webhooks auf deiner CI/CD

Um einen Webhook aus einer GitHub Action bereitzustellen, musst der workflow_dispatch Trigger zum on-Array deines Workflows hinzugefügt werden (Weitere Informationen zum manuellen Auslösen eines GitHub Workflows findest du hier: https://docs.github.com/de/actions/how-tos/manage-workflow-runs/manually-run-a-workflow):

name: Deploy GitHub Action

on:
  push:
  workflow_dispatch:

[...]

Durch diese Definition kann der Workflow mit einem POST-Request auf folgende URL gestartet werden:

https://<repositoryUrl>/api/v1/repos/<owner>/<repo>/actions/workflows/<workflowName>/dispatches

Für das Aufrufen dieses Webhooks wird aber noch der Body-Parameter ref benötigt. Dieser wird verwendet um zu wissen, von welcher git-Referenz aus der Workflow gestartet werden soll. Dabei kann es sich entweder um einen Branch-Namen oder einen Tag handeln.

In unserem Fall haben wir zwei verschiedene Deployment-Jobs im Workflow definiert: deploy_stage und deploy_live. Beide verwenden eine if-Bedingung, basierend auf der git-Referenz, um zu entscheiden, welches Deployment gestartet werden soll:

jobs:

  deploy_stage:
    name: 'Deploy to Stage'
  
    # only run on stage branch
    if: github.ref == 'refs/heads/stage'
  
    [...]
  
  deploy_live:
    name: 'Deploy to Live!'
  
    # only run on main branch
    if: github.ref == 'refs/heads/main'
  
    [...]

Dies bedeutet, dass wir folgenden JSON Payload in unserem Build trigger definieren müssen:

// JSON payload for "Deploy to Live"-Build Trigger
{
  "ref": "main"
}

// JSON payload for "Deploy to Stage"-Build Trigger
{
  "ref": "stage"
}

Einrichten der Statusbenachrichtigung im Webhooks

Damit in DatoCMS der aktuelle Stand des Deployments angezeigt werden kann, müssen wir dieses benachrichtigen, sobald der Deployment-Job abgeschlossen ist. Dies erreichen wir, indem wir die curl-Requests unter Step 2: Status notifications kopieren uns zu unserem Workflow-Schritten hinzufügen.

In unserem Fall sieht dies dann so aus:

jobs:

  [...]

  deploy_stage:
    name: 'Deploy to Stage'

    [...]
 
    steps:
      - name: Notify DatoCMS on success
        if: ${{ failure() && github.event_name == 'workflow_dispatch' }}
        run: |
          curl -n -X POST https://webhooks.datocms.com/<buildTriggerId>/deploy-results \
            -H 'Content-Type: application/json' \
            -d '{ "status": "success" }'
        
      - name: Notify DatoCMS on failure
        if: ${{ failure() && github.event_name == 'workflow_dispatch' }}
        run: |
            curl -n -X POST https://webhooks.datocms.com/<buildTriggerId>/deploy-results \
            -H 'Content-Type: application/json' \
            -d '{ "status": "error" }'

Bereit zum Deployment!

Die Content-Editoren sollten nun einen neuen Button in der rechten oberen Ecke des DatoCMS-Backends sehen mit der Bezeichnung "Build status".

Mit einem Klick darauf öffnet sich ein Menü in welchem die konfigurierten Build Triggers gestartet werden können. Darin wird sogar angezeigt, wenn gerade ein Deployment im Gange ist und ob das letzte Deployment erfolgreich war oder nicht.