GitHub Actions

Formfeed templates (formfeed-dev/formfeed-action) ist eine GitHub Action für Repositories, die ihre Vorlagen als Dateien führen. Sie führt die Kommandozeile formfeed in Ihrem Workflow aus: Jeder Push wird validiert und getestet, ein Pull Request zeigt die Dokumente, die er ändert, und der Standard-Branch veröffentlicht sie.

Vorbereitung

Ein Formfeed-Projekt im Repository: ein Ordner mit formfeed.json, einem Ordner templates/ mit einem Ordner je Vorlage und, wenn Vorlagen Partials einbinden, einem Ordner partials/. npx formfeed init legt ihn an, npx formfeed init --from-workspace holt zusätzlich die veröffentlichten Vorlagen Ihres Workspace. Siehe Vorlagen als Code.
Zwei API-Schlüssel als Secrets des Repositorys (Settings → Secrets and variables → Actions), so benannt wie im Workflow unten:
- FORMFEED_TEST_KEY, ein Test-Schlüssel (ff_test_…) mit den Standard-Scopes, für Validieren, Testen und Vorschauen. Seine Renderings kosten nichts.
- FORMFEED_LIVE_KEY, ein Schlüssel mit dem Scope template:write (der template:read einschließt), für den Schritt, der veröffentlicht. Siehe Scopes.
Die Region. Die Action hat dafür keine Eingabe: Die Kommandozeile nimmt sie aus region in formfeed.json oder aus FORMFEED_REGION im env des Jobs und verwendet ohne beides eu, die einzige Region, die heute rendert. Siehe Konfiguration.

Der Workflow

.github/workflows/templates.yml
name: templates
on:
  pull_request:
    paths: ['templates/**', 'partials/**']
  push:
    branches: [main]
    paths: ['templates/**', 'partials/**']

jobs:
  templates:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write # für den Vorschau-Kommentar
    steps:
      - uses: actions/checkout@v4
      - uses: formfeed-dev/formfeed-action@v1
        with:
          api-key: ${{ secrets.FORMFEED_TEST_KEY }}

      - if: github.event_name == 'push'
        uses: formfeed-dev/formfeed-action@v1
        with:
          api-key: ${{ secrets.FORMFEED_LIVE_KEY }}
          validate: false
          test: false
          publish: true

Der erste Schritt läuft bei jedem Ereignis mit dem Test-Schlüssel. Bei einem Pull Request validiert und testet er, rendert die Vorschauen und kommentiert; bei einem Push validiert und testet er nur, denn preview: auto rendert nur bei Pull Requests. Der zweite Schritt läuft nur bei Pushes auf main, mit dem Live-Schlüssel, und veröffentlicht. Passen Sie paths an, wenn formfeed.json andere Ordner für Vorlagen und Partials nennt, und working-directory, wenn das Projekt nicht im Wurzelverzeichnis des Repositorys liegt.

Was jeder Lauf tut

Validieren jeder Vorlage (formfeed validate): ihre Syntax, Variablen, die der Standard-Datensatz nicht hat, Kopf- und Fußzeile, Partials, die sie einbindet und die dem Projekt fehlen, bei einer Rechnungsvorlage den _invoice-Block jedes Datensatzes und bei einer Vorlage, die PDF/UA-1 festlegt (pdf.ua), die Befunde, die ihr Quelltext schon zeigt. Offline; ohne Schlüssel.
Testen jedes Datensatzes (formfeed test): Jeder wird kompiliert und analysiert, und seine Ausgabe, das zusammengesetzte HTML mit Kopf- und Fußzeile, wird mit dem freigegebenen Snapshot in templates/<slug>/tests/__snapshots__/<datensatz>.html verglichen (.xml bei Word- und PowerPoint-Vorlagen). Geben Sie die aktuelle Ausgabe mit npx formfeed test -u frei und committen Sie die Snapshots. Ein Datensatz ohne Snapshot wird gemeldet und lässt den Schritt nicht scheitern.
Vorschau eines Pull Requests: Die Vorlagen, die er ändert, werden über die API gerendert (formfeed ci preview), alle Vorlagen, wenn sich eine Datei im Ordner partials/ geändert hat. Jede wird aus den Dateien des Pull Requests mit ihrem Standard-Datensatz gerendert, es muss also vorher nichts gepusht werden; Word- und PowerPoint-Vorlagen werden im Job befüllt und über die API in PDF umgewandelt, was den Starter-Plan oder höher voraussetzt. Die Dateien werden zusammen mit der Zusammenfassung als Artefakt formfeed-preview hochgeladen, auch wenn ein Rendering fehlschlug. Die Zusammenfassung, eine Tabelle mit Datensatz, Seitenzahl und Link für jedes Dokument, steht am Pull Request als ein Kommentar, den jeder Lauf aktualisiert. Ihre Links sind signiert und laufen ab; die Dateien im Artefakt bleiben, solange GitHub Artefakte aufbewahrt. Jede Vorschau ist außerdem ein Rendering im Render-Log des Workspace, mit formfeed ci preview als meta.source.
Veröffentlichen, wenn publish gesetzt ist: formfeed templates push --publish mit dem SHA des Commits als Änderungsnotiz, oder formfeed templates push --channel <name>, wenn channel gesetzt ist. Siehe Veröffentlichen.

Ein Fehler lässt den Schritt und damit den Job scheitern, mit jedem Befund im Log: ein Validierungsfehler, ein fehlgeschlagener Snapshot-Vergleich, eine Vorlage, die nicht gerendert werden konnte, ein Push, den die API abgelehnt hat. Warnungen, etwa eine Variable, die der Standard-Datensatz nicht hat, werden ausgegeben und lassen nichts scheitern.

Eingaben

Eingabe	Standard	Was sie tut
`api-key`		Ein API-Schlüssel von Formfeed. Validieren und Testen laufen ohne ihn; Vorschauen und Veröffentlichen brauchen ihn. Ein Test-Schlüssel (`ff_test_…`) rendert Vorschauen kostenlos.
`working-directory`	`.`	Der Ordner des Formfeed-Projekts, der mit `formfeed.json`.
`version`	das Release, mit dem die Action kam	Die Version der Kommandozeile `formfeed`, die die Schritte ausführen, von npm.
`node-version`	`22`	Die Node.js-Version, auf der die Kommandozeile läuft.
`validate`	`true`	`formfeed validate` ausführen.
`test`	`true`	`formfeed test` gegen die freigegebenen Snapshots ausführen.
`preview`	`auto`	Die geänderten Vorlagen rendern. `auto` tut es bei Pull Requests, wenn `api-key` gesetzt ist; `true` rendert bei jedem Ereignis, `false` nie.
`base`	der Basis-Branch des Pull Requests	Die Git-Referenz, mit der die Vorschau vergleicht, etwa `origin/main`. Außerhalb von Pull Requests gibt es keinen Basis-Branch: Setzen Sie sie bei `preview: true`, sonst scheitert der Schritt.
`comment`	`true`	Die Zusammenfassung der Vorschau am Pull Request veröffentlichen und den eigenen Kommentar der Action aktualisieren. Nur bei Ereignissen `pull_request`; braucht `pull-requests: write`.
`publish`	`false`	Die Vorlagen pushen und veröffentlichen. Nur auf dem Standard-Branch setzen, mit einem Schlüssel, der `template:write` hat.
`channel`		Mit `publish` in diesen Release Channel pushen, statt zu veröffentlichen. Benannte Channels setzen den Starter-Plan oder höher voraus.
`github-token`	`${{ github.token }}`	Das Token, das den Kommentar schreibt.

Eingaben sind Zeichenketten: Schreiben Sie true und false wie gezeigt, jeder andere Wert gilt als aus.

Ausgaben

Ausgabe	Was sie ist
`summary`	Der absolute Pfad von `formfeed-preview.md` auf dem Runner, wenn eine Vorschau lief; sonst leer.

Geben Sie dem Schritt eine id, um sie in einem späteren Schritt desselben Jobs zu verwenden, etwa um die Zusammenfassung auch auf der Seite des Laufs zu zeigen:

- id: formfeed
  uses: formfeed-dev/formfeed-action@v1
  with:
    api-key: ${{ secrets.FORMFEED_TEST_KEY }}
- if: steps.formfeed.outputs.summary != ''
  run: cat "$SUMMARY" >> "$GITHUB_STEP_SUMMARY"
  env:
    SUMMARY: ${{ steps.formfeed.outputs.summary }}

Schlüssel und Berechtigungen

Schlüssel gehören in die Secrets des Repositorys. Verwenden Sie für Pull Requests einen Test-Schlüssel: Seine Renderings kosten nichts, seine Dateien werden nach einem Tag gelöscht, und im Free-Plan tragen sie die Testmarkierung. Der Schritt, der veröffentlicht, braucht einen Schlüssel mit template:write; geben Sie ihm keine weiteren Scopes. Vorlagen gehören zum Workspace, nicht zu einer Umgebung, deshalb veröffentlicht jeder Schlüssel mit diesem Scope, auch ein Test-Schlüssel: Halten Sie ihn vom Schlüssel Ihrer Pull Requests fern.
Berechtigungen: contents: read für den Checkout und pull-requests: write für den Kommentar. Ohne die zweite meldet die Action das als Warnung, und die Vorschauen liegen weiterhin im Artefakt.
Pull Requests aus Forks laufen ohne Ihre Secrets, deshalb überspringt auto dort die Vorschau; Validieren und Testen laufen trotzdem.
Historie: Die Vorschau vergleicht mit dem Basis-Branch, deshalb holt die Action die nötige Historie selbst. Ein Checkout mit fetch-depth: 0 erspart diesen Schritt.

Veröffentlichen

Jede Vorlage, jeder Lauf. templates push --publish erzeugt von jeder Vorlage des Projekts eine neue Version und veröffentlicht sie, auch von unveränderten, mit dem SHA des Commits als Änderungsnotiz. Eine Vorlage, die der Workspace noch nicht hat, wird angelegt. Mit channel behält eine Vorlage, deren Dateien noch dem entsprechen, was .formfeed/state.json festgehalten hat, die dort festgehaltene Version, jede andere bekommt eine neue Version, und der Channel wird darauf gesetzt.
.formfeed/state.json. Der Push sendet die dort festgehaltene Prüfsumme als base_checksum, und die Action committet die Datei nicht, die der Push aktualisiert. Liegt die Datei im Repository, wird der Push mit 409 conflict abgelehnt, sobald die neueste Version einer Vorlage im Workspace nicht mehr die ist, die die Datei festgehalten hat, und genau das bewirkt das Veröffentlichen der Action selbst; führen Sie dann formfeed templates pull aus und committen Sie die Datei erneut. Ein Repository, das nur über die Action veröffentlicht, kann die Datei weglassen (in .gitignore): Der Push sendet dann keine Prüfsumme und veröffentlicht die Dateien des Repositorys auch dann, wenn zwischendurch jemand im Editor eine andere Version veröffentlicht hat, die im Verlauf der Vorlage bleibt. Siehe Projektstruktur.
Brechende Schema-Änderungen. Eine Vorlage, die ein Datenschema speichert, wird geprüft, bevor sie live geht, und eine Änderung, die Aufrufer brechen würde, wird mit 409 schema_breaking_change abgelehnt. Die Action hat keine Eingabe für --allow-breaking: Veröffentlichen Sie eine solche Version selbst, mit Trotzdem veröffentlichen im Editor oder formfeed templates push --publish --allow-breaking. Siehe Die Schema-Prüfung.
Später veröffentlichen. Um eine Änderung vor dem Livegang auszuprobieren, setzen Sie channel: staging im Schritt, der veröffentlicht, und verschieben published in einem eigenen, manuellen Schritt; siehe Ein typischer Ablauf.

Versionen

@v1 ist das neueste Release der ersten Hauptversion der Action; eine Änderung, die einen heute funktionierenden Workflow brechen würde, kommt als v2. Um bei einem Release zu bleiben, nennen Sie es vollständig, etwa @v1.0.0. Die Eingabe version legt die Kommandozeile fest, die die Schritte ausführen: Standard ist das Release, mit dem die Action veröffentlicht wurde, und wer sie selbst setzt, hält einen Workflow auf der Version, die er getestet hat.

Die Schritte ausgeschrieben, ohne die Action, und dasselbe für GitLab stehen unter Einsatz in der CI.

Vorbereitung​

Der Workflow​

Was jeder Lauf tut​

Eingaben​

Ausgaben​

Schlüssel und Berechtigungen​

Veröffentlichen​

Versionen​