Cloudflare Workers in 47 Minuten mit GitHub Actions bereitstellen

Ein Cloudflare Worker in weniger als einer Stunde bereitgestellt? Das klingt einfacher, als es ist. Mein erster Versuch endete mit einem frustrierenden Authentifizierungsfehler – doch die Lösung lag in einer einzigen, oft übersehenen Einstellung. Hier erfahren Sie, wie Sie Ihre eigenen Edge-Funktionen mit GitHub Actions automatisieren und welche Fallstricke Sie von Anfang an vermeiden sollten.

Ein minimaler Worker, der den Unterschied macht

Das Ziel war simpel: Ein Worker, der bei einer Anfrage eine JSON-Antwort mit einer Begrüßung zurückgibt. Der Code selbst umfasst nur drei Zeilen Logik, ergänzt durch eine Konfigurationsdatei und ein GitHub-Actions-Workflow. Das Besondere daran ist nicht der Worker selbst, sondern der automatisierte Bereitstellungsprozess – denn einmal eingerichtet, lassen sich damit beliebig viele weitere Projekte mit minimalem Aufwand deployen.

Der Worker reagiert auf HTTP-Anfragen und gibt eine strukturierte Antwort zurück:

export default {
  async fetch(request, env, ctx) {
    return Response.json({
      message: "Hallo von der Edge",
      region: request.cf?.colo ?? "unbekannt",
    });
  },
};

Die Konfiguration erfolgt über die Datei wrangler.toml, die den Namen des Projekts und das Hauptskript definiert:

name = "hello-edge"
main = "src/index.js"
compatibility_date = "2025-01-01"

Der entscheidende Teil ist jedoch der GitHub-Actions-Workflow, der die Automatisierung übernimmt. Sobald Änderungen in den Hauptzweig (main) gepusht werden, startet der Workflow und stellt den Worker auf Cloudflares globaler Infrastruktur bereit:

name: Deploy Worker

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Drei Dateien, etwa 25 Zeilen Code – und doch steckt darin die Grundlage für eine effiziente Bereitstellungspipeline.

Der Fehler, der drei Minuten kostete

Die erste Ausführung des Workflows scheiterte innerhalb von elf Sekunden mit der Fehlermeldung Authentication error [code: 10000]. Ich überprüfte alles: Hatte ich das API-Token falsch eingegeben? War der Name des Secrets im GitHub-Repository falsch? Ich regenerierte das Token, doch der Fehler blieb bestehen. Nach sorgfältiger Lektüre der Dokumentation von wrangler-action und des Cloudflare-API-Tokens wurde mir klar: Das Problem lag nicht in der Syntax, sondern in den Berechtigungen.

Ich hatte ein API-Token mit der Vorlage „Read All Resources“ erstellt, um auf Nummer sicher zu gehen. Doch ein Worker benötigt Schreibrechte – und genau diese fehlten. Die Lösung war simpel: Ein neues Token mit der Vorlage „Edit Cloudflare Workers“ behebt das Problem, da es gezielt die notwendigen Berechtigungen für Worker zuweist. Der Fehlercode 10000 ist dabei irreführend, da er keinerlei Hinweis auf das tatsächliche Problem gibt.

Ein weiterer häufiger Irrtum: Die Account-ID ist öffentlich. Sie erscheint in der URL des Cloudflare-Dashboards und kann ohne Bedenken als GitHub-Secret gespeichert werden. Kritisch ist allein das API-Token – es sollte niemals in Protokollen oder öffentlichen Repositorys auftauchen. Ein versehentliches Leak erfordert umgehend eine Rotation des Tokens.

Warum Automatisierung von Tag eins an sinnvoll ist

Auf den ersten Blick mag die manuelle Bereitstellung über das Cloudflare-Dashboard mit der Option „Connect to Git“ attraktiv erscheinen. Für einfache Projekte ist das tatsächlich die schnellste Lösung. Doch der entscheidende Vorteil von GitHub Actions liegt in der Kontrolle und Erweiterbarkeit:

• Tests vor dem Deployment: Integration von Unit-Tests oder Linters in den Workflow.
• Staging-Umgebungen: Automatisierte Bereitstellung auf Test-Subdomains vor dem Live-Gang.
• Benachrichtigungen: Automatische Meldungen bei Fehlern, etwa per Slack oder E-Mail.
• Manuelle Freigaben: Einsatz von environments in GitHub Actions für kontrollierte Rollouts.

Die anfängliche Einrichtung dauert zwar etwa 15 Minuten länger als die manuelle Methode, doch dieser Aufwand lohnt sich für jedes Projekt, das über ein einfaches „Hello World“ hinausgeht. Für einmalige Marketingseiten oder Prototypen mag der direkte Weg über das Dashboard praktikabler sein – doch wer Flexibilität und Skalierbarkeit anstrebt, sollte frühzeitig auf Automatisierung setzen.

Der Moment der Wahrheit: Der erste erfolgreiche Deploy

Nach der Korrektur des API-Tokens startete der Workflow erneut – und diesmal verlief alles reibungslos. Die Log-Ausgabe zeigte:

Total Upload: 0.42 KiB / gzip: 0.30 KiB
Uploaded hello-edge (1.15 sec)
Deployed hello-edge triggers (0.32 sec)

Ein Klick auf den bereitgestellten Link führte zu einer Antwortzeit von nur 38 Millisekunden – gemessen von einem Server in Singapur, während ich mich in Batam, Indonesien, befand. Diese Distanz von etwa 60 Kilometern demonstriert die Leistungsfähigkeit von Cloudflares globalem Netzwerk.

Doch der eigentliche Erfolg lag nicht im Worker selbst, sondern in der Automatisierungspipeline. Das Gefühl, Code in den Hauptzweig zu pushen und innerhalb weniger Minuten eine globale Bereitstellung zu sehen – ohne das Cloudflare-Dashboard auch nur einmal zu öffnen – war befriedigender als jede manuelle Konfiguration.

Drei Lektionen für Ihren ersten Cloudflare Worker

Bevor Sie Ihren eigenen Worker mit GitHub Actions deployen, sollten Sie diese Punkte beachten:

• Nutzen Sie die „Edit Cloudflare Workers“-Vorlage für API-Tokens. Vermeiden Sie benutzerdefinierte Berechtigungen oder die Option „Read All Resources“, da diese zu unnötigen Fehlern führen können. Der Fehlercode 10000 gibt keinen Aufschluss über das tatsächliche Problem.

• Richten Sie die Pipeline vor dem eigentlichen Code ein. Ein einfacher Worker, der bereits automatisch bereitgestellt wird, ist wertvoller als ein komplexer Worker, den Sie manuell deployen. Die Pipeline spart Zeit und reduziert menschliche Fehler.

• Die Account-ID ist öffentlich – das API-Token nicht. Speichern Sie beide als GitHub-Secrets, aber verstehen Sie, welches der beiden Datenpunkte geschützt werden muss. Ein geleaktes Token ist eine ernsthafte Sicherheitslücke.

Was als Nächstes kommt: Preview-Deploys für Pull Requests

Der nächste logische Schritt ist die Integration von Preview-Deploys, die automatisch für jeden Pull Request erstellt werden. So kann das Team Änderungen vor dem Merge testen, ohne die Hauptumgebung zu gefährden. Der Workflow könnte um eine zweite Job-Definition erweitert werden, die bei pull_request-Events ausgelöst wird und eine temporäre Subdomain generiert.

Zusätzlich wäre ein Kommentar-Bot sinnvoll, der den Preview-Link direkt in der Pull-Request-Diskussion postet. So entfällt das manuelle Nachschlagen der URL.

Haben Sie bereits Erfahrung mit Cloudflare Workers und CI/CD? Welche Workflows nutzen Sie, und welche Fehler möchten Sie anderen Entwicklern ersparen? Teilen Sie Ihre Erfahrungen – die Community profitiert von Ihren Erkenntnissen.