Eine kleine Website. Muss man daraus wirklich ein Softwareprojekt machen?

FAXL.DE ist meine persönliche Website. Ich stelle dort eigene Projekte vor, schreibe über Softwareentwicklung und dokumentiere technische Themen, mit denen ich mich beschäftige.

Kein Onlineshop, kein Kundenportal, keine Benutzerverwaltung. Eigentlich brauche ich nur ein paar Seiten, die ordentlich aussehen, auf unterschiedlichen Geräten funktionieren und sich vernünftig pflegen lassen.

Dafür könnte ich ein Content-Management-System installieren, ein fertiges Theme auswählen und meine Texte über eine Weboberfläche eingeben. Das wäre sicherlich eine Möglichkeit.

Ich habe mich für einen anderen Weg entschieden.

FAXL.DE ist ein normales Softwareprojekt mit Quellcode, Versionsverwaltung, automatisierten Prüfungen und einer Deployment-Pipeline. Die Website wird lokal entwickelt, in GitHub verwaltet und bei STRATO veröffentlicht.

Das klingt für eine private Website zunächst nach mehr Aufwand als nötig. Tatsächlich steckt aber eine recht einfache Überlegung dahinter: Ich möchte Software entwickeln und Inhalte schreiben. Wiederkehrende technische Prüfungen und die Veröffentlichung sollen möglichst ohne mein Zutun funktionieren.

Und weil ich bei der Entwicklung Coding-Agenten wie Codex einsetze, kommt noch ein zweiter Punkt hinzu.

Ich möchte nicht für jeden Build, jeden Testlauf und jeden Datei-Upload erneut KI-Tokens verbrauchen.

↑ Nach oben

Das eigentliche Problem: Ein Coding-Agent ist kein Build-Server

Coding-Agenten können inzwischen ziemlich selbstständig an Software arbeiten. Sie lesen Dateien, verändern Code, starten Programme, führen Tests aus und versuchen, gefundene Probleme zu beheben.

Das nutze ich gern. Gerade bei Änderungen, die mehrere Dateien betreffen, kann ein Agent eine Menge Routinearbeit übernehmen.

Allerdings habe ich dabei eine Beobachtung gemacht: Ein erheblicher Teil der Arbeit eines Coding-Agenten besteht gar nicht aus Tätigkeiten, für die ich ein Sprachmodell brauche.

Nehmen wir eine einfache Änderung am Layout einer Website.

Der Agent verändert eine CSS-Regel, startet den Build und liest anschließend dessen Ausgabe. Vielleicht führt er noch ein paar Tests aus. Danach erklärt er mir, dass alles erfolgreich war.

Was davon benötigt tatsächlich künstliche Intelligenz?

Die Änderung der CSS-Regel möglicherweise schon. Zumindest kann der Agent mir helfen, das Problem zu verstehen und eine passende Lösung zu entwickeln.

Ob der TypeScript-Code gültig ist, entscheidet dagegen ein Prüfwerkzeug. Ob die Website gebaut werden kann, entscheidet der Build-Prozess. Ob ein interner Link auf eine existierende Seite zeigt, kann ein gewöhnliches Programm feststellen.

Dafür brauche ich kein Sprachmodell, das Konsolenausgaben liest und anschließend in eigenen Worten zusammenfasst.

Natürlich kostet das Ausführen eines lokalen Tests nicht automatisch Tokens. Der Verbrauch entsteht vor allem dann, wenn ein Coding-Agent Tests steuert, Ausgaben in seinen Modellkontext übernimmt und weitere Modellaufrufe für deren Auswertung benötigt.

Es gibt noch einen anderen Unterschied: Ein Test, der auf meinem Rechner erfolgreich war, beweist nicht automatisch, dass dieselbe Änderung in einer frischen Umgebung funktioniert.

Damit war die Zielsetzung klar.

Codex soll Änderungen entwickeln. GitHub soll unabhängig davon prüfen, ob sie technisch funktionieren. Und nach meiner Freigabe soll die Website automatisch veröffentlicht werden.

Das ist keine revolutionäre Architektur. Continuous Integration und Continuous Deployment gibt es schon lange. Für die Arbeit mit Coding-Agenten bekommen diese Konzepte aber einen zusätzlichen praktischen Nutzen.

↑ Nach oben

Warum FAXL.DE mit Astro gebaut ist

Für FAXL.DE verwende ich Astro.

Astro ist ein Webframework, mit dem sich unter anderem statische Websites erzeugen lassen. Aus Komponenten, Layouts, Markdown-Inhalten und anderen Projektdateien entsteht beim Build eine Sammlung fertiger Dateien.

Bei FAXL.DE sind das hauptsächlich HTML, CSS und die benötigten statischen Ressourcen.

Ein Webserver muss dafür keine Datenbank abfragen, keine Templates bei jeder Anfrage neu rendern und keine serverseitige Anwendung ausführen.

Der Ablauf ist ziemlich unspektakulär:

Astro-Komponenten
        +
Markdown-Inhalte
        +
CSS und statische Ressourcen
        |
        v
    Astro Build
        |
        v
       dist/
        |
        v
  Statischer Webspace
        |
        v
      Browser

Genau diese Einfachheit gefällt mir.

STRATO muss die erzeugten Dateien nur noch ausliefern. Der Browser bekommt eine fertige HTML-Seite und die dazugehörigen Ressourcen.

Das hat mehrere Vorteile.

Es gibt keine dauerhaft laufende Node.js-Anwendung auf dem Hosting-Paket. Es braucht keine zusätzliche Datenbank. Und die Angriffsfläche ist kleiner als bei einem System mit serverseitiger Programmlogik und zahlreichen Erweiterungen.

Das bedeutet natürlich nicht, dass eine statische Website automatisch sicher ist. Fehlerhafte Konfigurationen, problematische eingebundene Skripte oder unsichere Zugangsdaten sind weiterhin möglich.

Aber wenn ich keine dynamische Serveranwendung benötige, muss ich auch keine betreiben.

Warum nicht einfach HTML-Dateien schreiben?

Das wäre ebenfalls möglich. Bei wenigen Seiten funktioniert das sogar recht gut.

Spätestens wenn mehrere Artikel und Projektseiten dasselbe Layout verwenden sollen, wird es jedoch lästig.

Navigation, Seitentitel, Metadaten, Footer und responsive Darstellung sollen überall einheitlich sein. Gleichzeitig möchte ich nicht denselben HTML-Code in jeder Datei wiederholen.

Deshalb verwende ich Astro-Komponenten und gemeinsame Layouts.

Eine Änderung an einem Layout kann sich damit auf alle zugehörigen Seiten auswirken. Das ist praktisch, bringt aber auch eine Konsequenz mit sich: Eine fehlerhafte Änderung kann mehrere Seiten gleichzeitig betreffen.

Und genau deshalb sind automatisierte Prüfungen sinnvoll.

↑ Nach oben

Markdown für Inhalte, Astro für die Darstellung

Meine Projektbeschreibungen und Fachartikel liegen als Markdown-Dateien im Repository.

Vereinfacht sieht die Struktur so aus:

faxl-de/
├── public/
├── src/
│   ├── components/
│   ├── content/
│   │   ├── articles/
│   │   └── projects/
│   ├── layouts/
│   └── pages/
├── scripts/
├── tests/
├── .github/
│   └── workflows/
└── package.json

Ein Artikel besteht aus seinen Metadaten und dem eigentlichen Text.

Beispielsweise:

---
title: 'Ein technischer Fachartikel'
description: 'Eine kurze Beschreibung.'
topic: Softwareentwicklung
status: Fachartikel
order: 4
draft: true
routeSlug: beispielartikel
---

Darunter folgt der Markdown-Inhalt.

Astro verwaltet diese Dateien über sogenannte Content Collections. Dabei werden die Metadaten anhand eines Schemas geprüft.

Ein Artikel braucht beispielsweise einen Titel, eine Beschreibung und einen gültigen URL-Slug. Fehlt eine verpflichtende Angabe oder stimmt ihr Format nicht, kann die Prüfung einen Fehler melden.

Das ist eine kleine, aber wirkungsvolle Trennung.

Die Inhalte müssen keine vollständigen HTML-Seiten kennen. Die Darstellung muss nicht wissen, welcher Text später in einem Artikel steht. Und die technische Struktur kann unabhängig von den Artikeln weiterentwickelt werden.

Warum der öffentliche URL-Slug getrennt vom Dateinamen ist

Eine weitere Entscheidung betrifft die URLs.

Der Dateiname eines Artikels ist eine interne Angelegenheit des Repositories. Seine öffentliche Adresse sollte davon nicht zwingend abhängen.

Dafür gibt es bei FAXL.DE das Feld routeSlug.

Ein Artikel kann intern umbenannt werden, ohne dass sich seine öffentliche URL ändern muss.

Das ist wichtig, weil bestehende Links nicht nur auf meiner Website vorkommen. Sie können in E-Mails, Browser-Lesezeichen oder auf anderen Websites gespeichert sein.

Ein neuer Dateiname ist noch lange kein guter Grund für einen kaputten Link.

Entwürfe bleiben Entwürfe

Neue Artikel bekommen zunächst:

draft: true

Damit erscheinen sie nicht automatisch in den öffentlichen Übersichten oder als veröffentlichte Detailseite.

Erst nach einer inhaltlichen Freigabe wird daraus:

draft: false

Das ist kein Geheimschutz. Vertrauliche Informationen gehören ohnehin nicht in ein Repository, das später veröffentlicht werden könnte.

Es ist vielmehr eine redaktionelle Entscheidung: Ein Coding-Agent darf einen Artikel vorbereiten. Er entscheidet aber nicht selbst, wann ich ihn veröffentliche.

↑ Nach oben

Git ist die Grundlage für den gesamten Ablauf

Alle relevanten Projektdateien liegen in einem Git-Repository auf GitHub.

Git übernimmt dabei zwei Aufgaben.

Erstens kann ich nachvollziehen, wie sich das Projekt verändert hat. Jede eingecheckte Änderung gehört zu einem Commit. Ich kann Unterschiede betrachten und bei Bedarf zu einem früheren Stand zurückkehren.

Zweitens ermöglicht Git eine saubere Trennung zwischen Entwicklungsarbeit und der freigegebenen Website-Version.

Dafür gibt es den Branch main.

Er enthält den freigegebenen Projektstand.

Neue Änderungen entstehen dagegen auf einem eigenen Feature-Branch.

Ein typischer Ablauf sieht so aus:

git switch main
git pull --ff-only
git switch -c feature/neuer-artikel

Jetzt können Dateien verändert werden, ohne den freigegebenen Stand direkt anzutasten.

Bei der Entwicklung mit Codex habe ich eine klare Zuständigkeitsregel eingeführt.

Codex darf Dateien ändern und Tests ausführen. Commits, Pushes und Merges bleiben meine Entscheidung.

Das ist keine technische Notwendigkeit von Git oder Codex. Es ist schlicht die Arbeitsweise, die ich für mein Repository gewählt habe.

Der Agent soll mir die Entwicklung abnehmen, nicht eigenständig darüber entscheiden, welche Änderungen in die Versionshistorie übernommen oder veröffentlicht werden.

Wenn ich mit einer Änderung zufrieden bin, folgen die üblichen Git-Befehle:

git add .
git commit -m "Add new technical article"
git push -u origin feature/neuer-artikel

Damit liegt die Änderung auf GitHub, aber noch nicht auf main.

Und erst recht noch nicht automatisch auf meiner Website.

Dazwischen kommt ein Pull Request.

↑ Nach oben

Pull Requests sind meine Freigabestelle

Ein Pull Request, kurz PR, ist der Vorschlag, Änderungen aus einem Feature-Branch nach main zu übernehmen.

GitHub zeigt dabei die geänderten Dateien und die Unterschiede zum bisherigen Stand an.

Ich kann den Text eines Artikels lesen, eine Layoutänderung beurteilen und prüfen, ob der Umfang der Änderung zu meinem ursprünglichen Auftrag passt.

Der entscheidende Vorteil ist aber, dass GitHub an dieser Stelle zusätzlich technische Prüfungen ausführen kann.

Dafür verwende ich GitHub Actions.

GitHub Actions ist eine Automatisierungsplattform, die direkt mit GitHub-Repositories verbunden ist. Workflows werden durch Ereignisse wie einen Pull Request, einen Push oder eine manuelle Aktion gestartet.

Die Workflows liegen selbst im Repository.

Bei FAXL.DE befinden sie sich unter:

.github/workflows/

Damit ist auch die Automatisierung versioniert.

Ich kann nachvollziehen, wann eine Prüfung geändert wurde, welche Befehle ausgeführt werden und auf welcher Codeversion ein Ergebnis beruht.

Eine interessante Konsequenz: Die Prüfregeln sind nicht irgendeine Konfiguration auf meinem Windows-Rechner. Sie gehören zum Projekt.

↑ Nach oben

Fünf Prüfungen, bevor ich einen Pull Request merge

Für FAXL.DE gibt es den Workflow Website CI.

CI steht für Continuous Integration.

Der Workflow startet bei Pull Requests nach main und erneut, wenn weitere Commits in den zugehörigen Feature-Branch gepusht werden.

Er besteht aus fünf Jobs.

Job Aufgabe
Astro Check Prüft Astro-, TypeScript- und Content-Strukturen
Website Build Baut die vollständige statische Website
Linkchecker-Tests Prüft die Funktionsfähigkeit des Linkcheckers
Interne Links Prüft Links und Anker innerhalb der erzeugten Website
Externe Links Prüft die Erreichbarkeit verlinkter externer Webseiten

Diese Trennung ist Absicht.

Jeder Job hat eine konkrete Verantwortung. Wenn ein Test fehlschlägt, sehe ich nicht nur, dass „irgendetwas rot“ ist. Ich sehe, welcher Bereich betroffen ist.

Astro Check: Ist das Projekt technisch konsistent?

Der erste Job führt die Astro-Prüfung aus:

npx astro check

Dabei werden unter anderem relevante TypeScript- und Astro-Diagnosen ausgegeben.

Auch die Content-Strukturen gehören zur technischen Validierung.

Wenn ich beispielsweise ein verpflichtendes Frontmatter-Feld falsch angebe, soll das nicht erst auf der veröffentlichten Website auffallen.

Ein erfolgreicher Astro Check beweist noch nicht, dass die Website gut aussieht oder ein Artikel inhaltlich richtig ist.

Er bestätigt aber, dass die geprüften technischen Strukturen keine entsprechenden Fehler gemeldet haben.

Website Build: Kann aus dem Projekt eine Website entstehen?

Der zweite Job installiert die Abhängigkeiten reproduzierbar:

npm ci

Anschließend baut er die Website:

npm run build

Das Ergebnis liegt im Verzeichnis:

dist/

Dieses Verzeichnis enthält die Dateien, die später auf STRATO veröffentlicht werden.

Ein Build ist damit mehr als eine syntaktische Prüfung. Er erzeugt das konkrete Ausgabeprodukt.

Das ist gerade bei statischen Websites wichtig. Ein Fehler bei der Seitengenerierung kann dazu führen, dass eine erwartete Datei gar nicht entsteht.

Linkchecker-Tests: Funktioniert das Prüfwerkzeug selbst?

Der dritte Job prüft den Linkchecker.

Diesen habe ich als Python-Skript implementiert:

scripts/check_links.py

Die dazugehörigen Tests verwenden einen lokalen HTTP-Testserver.

Er kann unterschiedliche Antworten simulieren:

  • Erfolgreiche HTTP-Antworten
  • Weiterleitungen
  • Nicht vorhandene Seiten
  • Zugriffssperren
  • Rate-Limits
  • Timeouts
  • CAPTCHA-artige Antworten

Warum der Aufwand?

Weil ein Linkchecker nur so zuverlässig ist wie seine eigene Fehlerbehandlung.

Wenn beispielsweise ein Server HTTP 403 zurückliefert, ist der Link nicht automatisch kaputt. Vielleicht blockiert der Server nur automatisierte Anfragen.

Umgekehrt darf ein Link nicht als erreichbar gelten, wenn die Anfrage tatsächlich mit HTTP 404 endet.

Auch hier möchte ich nicht, dass ein Sprachmodell diese Unterscheidung anhand eines Logtextes errät. Das ist Aufgabe des Prüfprogramms.

Bei einer statischen Website lassen sich interne Links ziemlich gut prüfen.

Der Linkchecker untersucht die erzeugten HTML-Dateien und kontrolliert, ob ein verlinktes Ziel tatsächlich existiert.

Das betrifft nicht nur Seiten, sondern auch Sprungmarken.

Ein Link wie:

/wissen/beispielartikel/#technische-grundlagen

ist nur dann korrekt, wenn die Zielseite vorhanden ist und dort auch eine passende Anker-ID existiert.

Ebenso muss berücksichtigt werden, dass Astro für eine Route typischerweise eine index.html in einem entsprechenden Verzeichnis erzeugt.

Damit lässt sich eine ganze Klasse von Fehlern erkennen, bevor Besucher auf einen nicht funktionierenden Link klicken.

Bei externen Links ist die Situation schwieriger.

Ein fremder Webserver kann weiterleiten, temporär nicht erreichbar sein oder automatisierte Zugriffe blockieren.

Deshalb unterscheidet mein Linkchecker zwischen eindeutig defekten und nicht abschließend prüfbaren Zielen.

HTTP 404 oder 410 ist ein deutliches Signal, dass die angeforderte Ressource nicht mehr verfügbar ist.

HTTP 403, 429 oder ein Timeout kann dagegen verschiedene Ursachen haben.

Entsprechend unterscheidet die Prüfung die Ergebnisse:

ERREICHBAR
DEFEKT
UNBESTÄTIGT
NICHT GEPRÜFT

Ein grüner Job bedeutet dabei nicht zwangsläufig, dass jeder externe Link fachlich sinnvoll ist.

Er bedeutet zunächst, dass kein eindeutig defektes Ziel festgestellt wurde. Unbestätigte Ergebnisse müssen gesondert betrachtet werden.

Die technische Erreichbarkeit ersetzt schließlich auch keine inhaltliche Quellenprüfung. Eine Webseite kann HTTP 200 liefern und trotzdem etwas völlig anderes enthalten als erwartet.

↑ Nach oben

Warum der Build nicht fünfmal erzeugt wird

Ein weiterer Punkt betrifft die Effizienz der Pipeline.

Die internen und externen Linkprüfungen benötigen die fertigen HTML-Dateien, nicht den Entwicklungsquellcode allein.

Man könnte deshalb in jedem Linkprüfungsjob erneut npm ci und npm run build ausführen.

Das wäre unnötig.

Stattdessen erzeugt der Build-Job die Website einmal und stellt das Ergebnis als GitHub-Actions-Artefakt bereit.

Die beiden Linkjobs laden dieses Artefakt herunter und untersuchen dieselben erzeugten Dateien.

Vereinfacht sieht das so aus:

                  Pull Request
                       |
          +------------+------------+
          |            |            |
          v            v            v
      Astro Check   Website Build  Linkchecker-Tests
                       |
                       v
                  dist/-Artefakt
                       |
                +------+------+
                |             |
                v             v
         Interne Links   Externe Links

Das spart doppelte Build-Arbeit und stellt sicher, dass beide Linkprüfungen auf demselben Build-Ergebnis arbeiten.

Außerdem kann ich bei einem fehlgeschlagenen externen Linkcheck gezielt diesen Job erneut starten.

Ich muss dafür nicht zwangsläufig den gesamten Build wiederholen.

Gerade bei vorübergehenden Netzwerkproblemen ist das praktisch.

↑ Nach oben

Was passiert, wenn ein Job rot wird?

Das lässt sich direkt in GitHub beobachten.

Im Pull Request zeigt GitHub den Zustand der einzelnen Jobs an. Im Bereich Actions finde ich außerdem die Protokolle und Zusammenfassungen.

Angenommen, ich habe einen Artikel ergänzt und dessen externe Linkprüfung schlägt fehl.

Dann sehe ich im entsprechenden Job, welcher Link betroffen ist und welche HTTP-Antwort zurückgegeben wurde.

Falls der Zielserver nur vorübergehend nicht erreichbar war, kann ich den Job erneut starten.

GitHub erlaubt dafür unter anderem:

  • Alle Jobs erneut ausführen
  • Fehlgeschlagene Jobs erneut ausführen
  • Einen einzelnen Job erneut ausführen

Wenn der Fehler dagegen in meinem Quellcode liegt, korrigiere ich ihn auf dem Feature-Branch.

Nach dem nächsten Commit und Push startet die CI automatisch erneut.

Ich muss Codex also nicht anweisen, denselben vollständigen Prüfprozess noch einmal zu orchestrieren und mir anschließend die Ergebnisse zusammenzufassen.

GitHub erledigt die wiederkehrende Arbeit. Der Coding-Agent wird erst wieder gebraucht, wenn tatsächlich eine Codeänderung erforderlich ist.

Warum ich trotzdem selbst merge

Mein Repository ist privat und läuft unter GitHub Free.

Für diese Kombination stehen mir nicht dieselben verbindlichen Branch-Protection-Funktionen zur Verfügung wie in höheren Tarifen. Die CI-Ergebnisse werden angezeigt, aber eine technisch erzwungene Merge-Sperre ist in meinem Ablauf nicht eingerichtet.

Das stört mich für diese Website nicht besonders.

Ich habe ohnehin entschieden, dass ich jeden Pull Request selbst freigebe.

Meine Regel ist einfach: Erst wenn die relevanten Prüfungen erfolgreich sind und ich den Inhalt kontrolliert habe, merge ich nach main.

Ein automatischer Merge wäre möglich, wenn die entsprechenden Voraussetzungen und Funktionen genutzt würden. Ich möchte ihn hier nicht.

Die Maschine prüft. Ich entscheide.

↑ Nach oben

Nach dem Merge beginnt das Deployment

Mit einem Merge liegt die freigegebene Änderung auf main.

Der nächste Schritt ist das Deployment, also die Veröffentlichung der Website.

Anfangs habe ich dafür lokal einen Build erstellt und die Dateien mit FileZilla per SFTP auf meinen STRATO-Webspace übertragen.

Das funktioniert, hat aber einen entscheidenden Nachteil: Es ist ein manueller, wiederkehrender Arbeitsschritt.

Ich muss daran denken, den richtigen Build zu verwenden, die richtigen Dateien hochzuladen und veraltete Dateien auf dem Server zu entfernen.

Besonders der letzte Punkt wird gerne vergessen.

Wenn ich beispielsweise einen Artikel aus meinem Repository entferne, soll dessen HTML-Datei natürlich auch nicht mehr auf dem Webserver liegen.

Ein bloßes Hochladen neuer und veränderter Dateien reicht dafür nicht aus.

Deshalb ist das Deployment bei FAXL.DE als vollständige Synchronisation ausgelegt.

↑ Nach oben

Nicht kopieren, sondern den Build spiegeln

Die maßgebliche Quelle für die veröffentlichte Website ist das beim Build erzeugte Verzeichnis dist/.

Nicht der Git-Worktree direkt. Nicht eine beliebige lokale Kopie. Und auch nicht das, was zufällig noch auf dem Webspace liegt.

Das Deployment vergleicht den aktuellen Build mit dem vorhandenen Serverbestand.

Daraus ergeben sich vier Fälle:

Zustand Aktion
Datei existiert nur im Build Hochladen
Datei existiert auf beiden Seiten, Inhalt unterschiedlich Ersetzen
Datei existiert auf beiden Seiten, Inhalt identisch Überspringen
Datei existiert nur auf dem Server Löschen

Nicht mehr benötigte leere Verzeichnisse werden anschließend ebenfalls entfernt.

Das Ziel ist eindeutig:

Nach einem erfolgreichen Deployment muss der Inhalt des vorgesehenen Website-Verzeichnisses dem aktuellen dist/-Build entsprechen.

Wenn ich eine Datei aus dem Projekt entferne, soll sie nicht auf STRATO liegen bleiben.

Wenn ich eine CSS-Datei verändere, soll die neue Version veröffentlicht werden.

Wenn sich eine Datei nicht verändert hat, muss sie nicht erneut übertragen werden.

Und wenn ich einen früheren Git-Stand erneut veröffentliche, soll der Webspace anschließend genau diesen Stand widerspiegeln.

Für eine statische Website ist das ein sehr angenehmes Betriebsmodell.

↑ Nach oben

Warum ich SFTP und Python verwende

Die Website liegt bei STRATO auf einem gewöhnlichen Hosting-Paket.

Ich benötige dort weder einen Docker-Container noch einen eigenen Build-Server. Die Website wird bereits bei GitHub vollständig erzeugt.

Der Server muss die Dateien nur empfangen und ausliefern.

Für den Transport verwende ich SFTP über SSH auf Port 22.

Der Deployment-Kern ist in Python implementiert und verwendet die Bibliothek Paramiko.

Die eigentliche Übertragungslogik liegt damit in einem gemeinsamen Programm, das sowohl lokal unter Windows als auch auf einem GitHub-Runner ausgeführt werden kann.

Ich wollte bewusst nicht zwei voneinander unabhängige Deployment-Verfahren entwickeln.

Ein PowerShell-Skript für Windows und ein separates Bash-Skript für GitHub hätten zwar funktioniert. Aber dann müsste ich Änderungen am Dateivergleich, an der Fehlerbehandlung oder an den Löschregeln zweimal implementieren.

Stattdessen bleibt die Arbeitsteilung einfach:

Lokal unter Windows           GitHub Actions
        |                           |
        v                           v
    PowerShell                 Workflow-YAML
        |                           |
        +-------------+-------------+
                      |
                      v
                Python-CLI
                      |
                      v
           Gemeinsamer SFTP-Kern
                      |
                      v
               STRATO-Webspace

PowerShell ist der lokale Einstiegspunkt.

GitHub Actions übernimmt die automatische Ausführung.

Die eigentliche Synchronisation ist dieselbe.

↑ Nach oben

Was das Deployment technisch macht

Der Ablauf besteht aus einigen klar getrennten Schritten.

1. Build prüfen

Bevor überhaupt eine Verbindung zum Webserver aufgebaut wird, untersucht ein Preflight-Skript den lokalen Build.

Es erwartet unter anderem eine vorhandene, nicht leere index.html und die benötigte .htaccess.

Außerdem prüft es die Dateien und erzeugt ein Manifest.

Ein Eintrag enthält sinngemäß:

Dateipfad
Dateigröße
SHA-256-Prüfsumme

Die SHA-256-Prüfsumme ist ein Hashwert des Dateiinhalts.

Zwei Dateien mit gleicher Größe müssen nicht denselben Inhalt haben. Deshalb ist die Dateigröße allein kein verlässliches Kriterium dafür, ob etwas übertragen werden muss.

Die Prüfsumme erlaubt dagegen einen sehr zuverlässigen Inhaltsvergleich.

2. Remote-Bestand lesen

Anschließend verbindet sich der SFTP-Kern mit STRATO.

Er liest die vorhandenen Dateien, bestimmt ihre Größen und berechnet auch für sie SHA-256-Prüfsummen.

Diese Daten bilden das Remote-Inventar.

Erst wenn der Bestand vollständig erfasst werden konnte, wird daraus ein Synchronisationsplan erstellt.

3. Änderungen planen

Der lokale Build wird mit dem Remote-Inventar verglichen.

Das Ergebnis zeigt, welche Dateien neu sind, welche ersetzt werden müssen, welche identisch sind und welche auf dem Server nicht mehr benötigt werden.

Diesen Plan kann ich im Dry-Run betrachten, ohne irgendetwas auf STRATO zu verändern.

4. Dateien übertragen und prüfen

Bei einem produktiven Deployment werden neue und veränderte Dateien übertragen.

Die Implementierung verwendet dafür temporäre Dateinamen. Nach dem Upload wird der Inhalt über SFTP zurückgelesen und seine SHA-256-Prüfsumme verglichen.

Erst wenn die Übertragung erfolgreich geprüft wurde, wird die Datei am endgültigen Ziel bereitgestellt.

Für die Ersetzung vorhandener Dateien verwendet der SFTP-Kern die Servererweiterung posix_rename. Wenn der Server sie nicht unterstützt, bricht das Deployment ab.

Damit soll verhindert werden, dass eine noch unvollständig übertragene Datei bereits unter ihrem endgültigen Namen ausgeliefert wird.

Das ist allerdings nicht dasselbe wie ein atomarer Release der gesamten Website. Die Dateien werden weiterhin einzeln aktualisiert.

5. Nicht mehr benötigte Dateien entfernen

Nach erfolgreicher Übertragung werden Dateien entfernt, die im aktuellen Build nicht mehr vorhanden sind.

Auch dadurch unterscheidet sich das Verfahren von einem einfachen FTP-Upload.

Eine alte Artikeldatei darf nicht dauerhaft erreichbar bleiben, nur weil ich sie irgendwann einmal veröffentlicht habe.

Nicht mehr benötigte und leer gewordene Verzeichnisse können anschließend ebenfalls entfernt werden.

6. Endzustand kontrollieren

Zum Schluss wird der Remote-Bestand erneut geprüft.

Der erfolgreiche Endzustand ist erreicht, wenn die vorgesehenen Dateien und ihre Inhalte mit dem lokalen Build-Manifest übereinstimmen und keine überzähligen Dateien mehr im verwalteten Zielverzeichnis liegen.

Ein fehlgeschlagener Vergleich ist kein erfolgreicher Deployment-Lauf.

Damit ist klar, was ein grüner Deployment-Job bedeutet: Nicht nur, dass ein Skript ohne sichtbaren Fehler beendet wurde, sondern dass der geprüfte Zielbestand dem erwarteten Build entspricht.

↑ Nach oben

Woher GitHub die SFTP-Zugangsdaten bekommt

Ein GitHub-Runner muss sich bei STRATO anmelden können.

Dafür braucht er Hostname, Benutzername, Zugangsdaten und die Information, in welchem Verzeichnis die Website liegt.

Diese Angaben gehören nicht alle in den Quellcode.

Insbesondere das Passwort darf nicht in einer Workflow-Datei stehen, die versioniert und von den Entwicklungswerkzeugen gelesen wird.

GitHub bietet dafür Actions Secrets.

Das sind verschlüsselt gespeicherte Werte, die ein Workflow bei seiner Ausführung verwenden kann.

Bei FAXL.DE werden darüber die SFTP-Verbindungsdaten und der vertrauenswürdige öffentliche SSH-Host-Key bereitgestellt.

Die Host-Key-Prüfung ist wichtig, damit sich der Client nicht einfach mit irgendeinem Server verbindet, der unter der angefragten Adresse antwortet.

Für den GitHub-Workflow ist dabei kein interaktiver Dialog vorgesehen. Er muss anhand einer vorher festgelegten Vertrauenskonfiguration entscheiden können, ob er mit dem richtigen Server spricht.

Auch das ist eine Aufgabe für normale Software und nicht für ein Sprachmodell.

Eine Besonderheit bei STRATO: Das SFTP-Wurzelverzeichnis

Für FAXL.DE verwende ich einen eigenen SFTP-Zugang.

Dieser ist bei STRATO auf das Website-Verzeichnis /faxl-de eingerichtet.

Innerhalb der SFTP-Sitzung sieht der Benutzer dieses Verzeichnis als /.

Das kann zunächst irritieren.

Der Pfad / bedeutet in diesem Fall nicht zwangsläufig das Wurzelverzeichnis des gesamten Servers, sondern das vom Anbieter für diesen Zugang bereitgestellte Startverzeichnis.

Die Deployment-Software muss trotzdem wissen, für welchen Zugang sie arbeitet und welches Ziel ausdrücklich freigegeben ist.

Deshalb wird die Root-Konfiguration geprüft, bevor schreibende Operationen möglich sind.

Der Zugang ist für die Website vorgesehen. Dass / in der Sitzung als Startverzeichnis erscheint, beweist für sich allein aber keine technisch erzwungene Isolation gegenüber übergeordneten Verzeichnissen. Die Software prüft Pfade und Zielkonfiguration, die tatsächliche Begrenzung des Zugangs muss separat beurteilt werden.

↑ Nach oben

Zwei GitHub-Workflows mit unterschiedlichen Aufgaben

Die Qualitätsprüfung und die Veröffentlichung sind bei FAXL.DE bewusst getrennt.

Der erste Workflow heißt:

Website CI

Er prüft Änderungen im Pull Request.

Der zweite übernimmt das Deployment.

Diese Trennung hat einen praktischen Vorteil: Ein fehlgeschlagener Test ist nicht automatisch ein teilweise ausgeführter Upload.

Die CI liefert zunächst die Information, ob die Änderungen technisch in Ordnung sind.

Erst nach dem manuellen Merge nach main beginnt die Veröffentlichung.

Der Deployment-Workflow baut den freigegebenen Stand, führt seine vorgesehenen Prüfungen aus und synchronisiert anschließend dist/ mit STRATO.

Ein vereinfachter Ablauf sieht so aus:

Codex / lokale Entwicklung
            |
            v
       Feature-Branch
            |
            v
       Commit und Push
            |
            v
        Pull Request
            |
            v
      GitHub Actions CI
            |
            v
      Alle Checks grün?
            |
         Ja |
            v
       Manueller Merge
            |
            v
           main
            |
            v
    GitHub Actions Deploy
            |
            v
    Astro-Build + Prüfungen
            |
            v
       SFTP-Abgleich
            |
            v
     Upload / Ersetzen
     Löschen / Verifizieren
            |
            v
         FAXL.DE

Der Auslöser ist ein geschlossenes Pull-Request-Ereignis, bei dem der PR tatsächlich nach main gemergt wurde. Ein gewöhnlicher Push auf main, ein nur geschlossener PR und ein PR gegen einen anderen Zielbranch starten kein automatisches Deployment. Der Workflow besitzt dafür keinen push-Trigger.

Für den Build verwendet der Workflow den merge_commit_sha des gemergten PR. Bei Merge-Commit, Squash und Rebase bezeichnet GitHub damit den integrierten Stand auf dem Zielbranch. Die GitHub-Dokumentation beschreibt die Unterschiede. Vor dem Upload vergleicht der Workflow den ausgecheckten Stand erneut mit der aktuellen Spitze von main. Stimmen sie nicht überein, bricht er ab, statt einen veralteten Stand zu veröffentlichen.

Schreibende Läufe teilen sich eine Concurrency-Gruppe und laufen nicht gleichzeitig. Während eines bereits laufenden Uploads kann allerdings ein neuer Merge stattfinden. Dessen eigener Lauf muss dann den neueren Stand veröffentlichen. Fehlgeschlagene Pflichtprüfungen verhindern den Upload. Unbestätigte externe Links bleiben trotz eines grünen Linkchecker-Jobs ein Prüfvorbehalt.

Der manuelle Produktivlauf der Synchronisation war erfolgreich. Der automatische Merge-Trigger ist implementiert, sein erster produktiver Lauf steht zum Zeitpunkt dieses Artikels noch aus.

Zusätzlich ist eine manuelle Ausführung sinnvoll.

Damit kann ich beispielsweise einen Deployment-Lauf für den aktuellen main-Stand wiederholen. Die manuellen Modi heißen offline-preflight, remote-dry-run und manual-deploy. Nur der letzte schreibt und benötigt die vorgesehenen Bestätigungen.

Der manuelle Einstieg bleibt außerdem als Möglichkeit erhalten, wenn die automatische Ausführung einmal nicht das gewünschte Ergebnis liefert.

↑ Nach oben

Warum ich weiterhin ein lokales PowerShell-Skript habe

GitHub Actions ist für die reguläre Veröffentlichung zuständig.

Trotzdem möchte ich nicht vollständig davon abhängig sein.

Wenn ich aus irgendeinem Grund lokal deployen möchte, kann ich das über PowerShell tun.

Der Einstieg verwendet denselben Python-Kern und dieselben Regeln für Manifest, Dateiübertragung, Löschung und Verifikation.

Für den lokalen Offline-Preflight sieht der Aufruf beispielsweise so aus:

./scripts/deploy.ps1 -Python ./.venv/Scripts/python.exe

Ein Remote-Dry-Run wird ausdrücklich aktiviert:

./scripts/deploy.ps1 `
  -Python ./.venv/Scripts/python.exe `
  -Remote `
  -TargetConfirmed `
  -AllowConfinedRoot

Für einen produktiven Upload kommt eine zusätzliche Schreibfreigabe hinzu.

Die benötigten Zugangsdaten müssen lokal in der vorgesehenen sicheren Konfiguration verfügbar sein.

Das PowerShell-Skript ist damit keine zweite Deployment-Architektur. Es ist lediglich ein anderer Einstiegspunkt in denselben Ablauf.

Diese Wiederverwendung ist mir wichtiger als eine möglichst große Auswahl unterschiedlicher Werkzeuge.

↑ Nach oben

Was bei einem fehlgeschlagenen Deployment passiert

Ein Deployment kann natürlich scheitern.

Die Netzwerkverbindung kann abbrechen. Ein Dateizugriff kann verweigert werden. Eine Serverfunktion kann sich anders verhalten als erwartet.

Die Pipeline muss solche Fehler erkennen und als Fehler melden.

Bei GitHub Actions bedeutet das einen roten Job.

Ich kann das Protokoll ansehen und anschließend entscheiden, ob ein erneuter Lauf sinnvoll ist oder ob zunächst ein Problem behoben werden muss.

Eine Einschränkung bleibt bei dieser Architektur bestehen: Die komplette Website wird nicht in einem einzigen atomaren Schritt umgeschaltet.

Wenn ein Deployment nach einigen erfolgreich übertragenen Dateien abbricht, können kurzfristig Dateien unterschiedlicher Versionen auf dem Server liegen.

Für FAXL.DE akzeptiere ich diese Einschränkung.

Es ist eine private, statische Website ohne Bestellungen, Kundendaten oder Transaktionen. Ich brauche dafür keine komplexe Release-Infrastruktur mit separaten Staging-Verzeichnissen, Datenbankmigrationen und automatischen Rollback-Mechanismen.

Git enthält die Versionshistorie.

Wenn ich zu einem früheren Stand zurückkehren möchte, kann ich dessen Änderungen über einen neuen Pull Request auf main zurückführen. Alternativ kann ich einen bekannten Git-Stand lokal bauen und über den ausdrücklich freigegebenen PowerShell-Einstieg veröffentlichen. Der manuelle GitHub-Workflow selbst akzeptiert nur den aktuellen main-Stand.

Dabei ist wichtig, dass das Deployment wirklich synchronisiert und nicht nur Dateien hinzufügt. Sonst könnten Dateien aus einer neueren Version auf dem Server zurückbleiben.

Die Wiederherstellung ist also keine magische Rückgängig-Funktion. Sie besteht darin, einen ausgewählten, bekannten Stand erneut vollständig auszurollen.

Für diese Website reicht mir das.

↑ Nach oben

Und wo spart das nun KI-Tokens?

Damit komme ich zu dem Punkt, der für mich eigentlich ausschlaggebend war.

Ich habe die GitHub-Actions-Pipeline nicht eingerichtet, weil ich unbedingt möglichst viele grüne Häkchen auf einer GitHub-Seite sehen möchte.

Ich möchte die Arbeit eines Coding-Agenten auf die Aufgaben konzentrieren, bei denen er tatsächlich hilfreich ist.

Nehmen wir einen typischen Auftrag:

Ergänze einen Fachartikel, passe die Navigation an und achte darauf, dass die bestehende Darstellung erhalten bleibt.

Codex kann dafür den Code und die Inhalte untersuchen, Änderungen vorbereiten und gegebenenfalls gezielte lokale Prüfungen durchführen.

Ohne eine eigenständige Pipeline würde ich anschließend vielleicht denselben Agenten bitten:

Prüfe noch einmal das komplette Projekt, starte den Build, kontrolliere alle Links und lade die neue Version hoch.

Der Agent müsste Werkzeuge ausführen, Ergebnisse lesen, eventuelle Fehler interpretieren und mir den Ablauf zusammenfassen.

Ein Teil davon wäre vernünftig, vor allem wenn die Tests weitere Änderungen am Code erfordern.

Ein großer Teil ist aber reine Routine.

Mit GitHub Actions läuft diese Routine unabhängig vom Sprachmodell.

Der Coding-Agent muss nicht dauerhaft beteiligt sein, während ein Build ausgeführt wird. Er muss nicht jede Zeile eines erfolgreichen Testlaufs lesen. Und er muss auch keine SFTP-Dateiliste verarbeiten, um festzustellen, welche Dateien hochgeladen werden sollen.

Die Werkzeuge liefern selbst strukturierte Ergebnisse.

GitHub speichert die Protokolle und stellt den Status dar.

Wenn alles grün ist, ist kein weiterer Modellaufruf nötig.

Wenn etwas fehlschlägt, kann ich den betroffenen Job gezielt untersuchen oder den Fehler wieder an Codex übergeben.

Das ist der eigentliche Gewinn: Die KI beschäftigt sich mit der Lösung eines Problems. Deterministische Werkzeuge prüfen und veröffentlichen das Ergebnis.

Spart das wirklich Geld?

Hier lohnt sich eine Unterscheidung.

GitHub Actions verbraucht weiterhin Rechenzeit. Builds und Tests verschwinden nicht, nur weil sie nicht mehr lokal laufen.

Auch kann ein Coding-Agent weiterhin Tokens verbrauchen, wenn er im Rahmen der Entwicklung selbst Tests startet und deren Ergebnisse verarbeitet.

Die Einsparung entsteht vor allem dadurch, dass standardisierte Prüf- und Deployment-Aufgaben nicht mehr vom Agenten orchestriert und sprachlich ausgewertet werden müssen.

Wie viele Tokens dadurch tatsächlich eingespart werden, hängt vom bisherigen Arbeitsablauf ab.

Eine pauschale Prozentangabe wäre unseriös.

Der Vorteil liegt für mich deshalb nicht nur in möglichen Kostenersparnissen, sondern auch in der klaren Trennung der Verantwortlichkeiten.

Ein Testlauf braucht kein sprachliches Urteil, wenn seine Erfolgskriterien bereits eindeutig definiert sind.

↑ Nach oben

Warum ich den Coding-Agenten trotzdem lokal testen lasse

Die Verlagerung zu GitHub bedeutet nicht, dass Codex überhaupt keine Tests mehr ausführen soll.

Wenn ein Agent eine Python-Funktion verändert, ist es sinnvoll, unmittelbar die betroffenen Unit-Tests zu starten.

Sonst müsste ich jede kleine Korrektur erst committen und pushen, um überhaupt zu erfahren, ob sie funktioniert.

Der Unterschied liegt im Umfang.

Lokal prüfe ich gezielt während der Entwicklung. GitHub übernimmt die vollständige, standardisierte Prüfung des Integrationsstands.

So kann der Agent schnell auf konkrete Fehler reagieren, ohne bei jeder kleinen Änderung die gesamte Website-Pipeline erneut durchlaufen zu müssen.

Gleichzeitig bekomme ich beim Pull Request die Bestätigung, dass das Projekt in einer anderen Umgebung gebaut und geprüft werden konnte.

Das ist ein wesentlicher Unterschied zu der Aussage „Auf meinem Rechner funktioniert es“.

↑ Nach oben

Was ich aus der Umsetzung mitgenommen habe

Die Einrichtung war nicht in jedem Schritt reibungslos.

Ein früher CI-Lauf scheiterte beispielsweise an einem Linkchecker-Test, dessen lokaler HTTP-Testserver auf unterschiedliche Anfragearten widersprüchlich reagierte.

Der Test konnte lokal bestehen und auf einem GitHub-Runner fehlschlagen.

Genau solche Unterschiede sind interessant.

Sie zeigen, warum es sinnvoll ist, Tests nicht ausschließlich in der Entwicklungsumgebung auszuführen.

Auch beim SFTP-Deployment gab es ein praktisches Detail, das man in einer abstrakten Architekturzeichnung leicht übersieht: Das bei STRATO konfigurierte Startverzeichnis und das innerhalb der SFTP-Sitzung sichtbare Wurzelverzeichnis sind nicht zwingend derselbe Pfad.

Solche Dinge erkennt man erst, wenn die eigene Software mit der tatsächlichen Zielumgebung zusammenarbeitet.

Das heißt nicht, dass man für eine private Website eine riesige Sicherheitsarchitektur benötigt.

Im Gegenteil.

Ich habe für dieses Projekt bewusst darauf verzichtet, zusätzliche Backup-Systeme, komplexe Rollback-Mechanismen oder eine eigene Serverinfrastruktur einzuführen.

Die vorhandenen Werkzeuge reichen aus: Git für die Versionshistorie, GitHub Actions für Prüfungen und Automatisierung, Python für die Synchronisation und STRATO für die Auslieferung.

Mehr Technik wäre hier nicht automatisch besser.

↑ Nach oben

Eine klare Grenze zwischen Entwicklung und Betrieb

FAXL.DE ist technisch kein besonders großes Projekt.

Gerade deshalb eignet es sich gut, um eine saubere Arbeitsteilung umzusetzen.

Astro erzeugt die Website.

Markdown enthält die Inhalte.

Git verwaltet die Versionen.

Codex hilft mir bei Entwicklungsaufgaben.

GitHub Actions führt die standardisierten Prüfungen aus.

Ich entscheide, welche Änderungen nach main gelangen.

Und die Deployment-Pipeline sorgt dafür, dass der freigegebene Build auf STRATO landet.

Das ist letztlich die Architektur, die ich haben wollte.

Nicht weil eine private Website unbedingt eine CI/CD-Pipeline benötigt. Sondern weil ich möglichst wenig Zeit und KI-Kontext auf Aufgaben verwenden möchte, die sich mit gewöhnlichen Werkzeugen zuverlässig automatisieren lassen.

Ein Coding-Agent darf gern über Architektur nachdenken, Code entwickeln und schwierige Fehler analysieren.

Ob eine Datei hochgeladen werden muss, sollte er nicht jedes Mal neu überlegen müssen.

↑ Nach oben