jdevalk/skills

Astro GitHub Actions

Dieses Skill hilft Ihnen, eine umfassende CI/CD-Pipeline für Astro-Seiten mit GitHub Actions einzurichten. Ziel ist es, Autoren zu ermöglichen, qualitativ hochwertigere Websites mit weniger manuellem Aufwand zu veröffentlichen: Typfehler werden vor dem Merge erkannt, defekte Links gemeldet, Builds verifiziert und Deployments automatisiert.

Was dieses Skill abdeckt

Es gibt mehrere Kategorien von Workflows, die ein gesundes Astro-Projekt haben sollte. Nicht jede Seite benötigt alle – die richtige Mischung hängt davon ab, ob das Projekt TypeScript, benutzerdefinierte Komponenten, Content Collections, Tests verwendet und wo es deployed wird. Ihre Aufgabe ist es, herauszufinden, welche relevant sind, und diese einzurichten.

Die Workflows fallen in diese Kategorien:

1. Typ-/Content-Prüfung – astro check (TypeScript + Content-Collection-Schema-Validierung)
2. Code-Qualität – ESLint und Prettier
3. Build-Verifizierung – astro build läuft sauber durch
4. Tests – Vitest für Unit- und Komponententests
5. Qualitäts-Schleusen – Lighthouse CI (Performance, Barrierefreiheit, SEO, Best Practices)
6. Link-Checking – Erkennung defekter Links auf der gebauten Seite
7. Sicherheit – npm audit für Abhängigkeits-Schwachstellen
8. Deployment – GitHub Pages, Cloudflare Pages, Netlify oder Vercel

Lesen Sie references/workflows.md für die detaillierte Konfiguration jedes Workflows, einschließlich gebrauchsfertiger YAML-Vorlagen und Konfigurationsdateien.

Wie man eine Anfrage angeht

Schritt 1: Das Projekt verstehen

Bevor Sie Workflow-Dateien schreiben, ermitteln Sie, womit Sie es zu tun haben:

• Ist es TypeScript? Überprüfen Sie auf tsconfig.json und .ts/.astro-Dateien. Fast jedes Astro-Projekt sollte astro check ausführen, aber der Wert ist am höchsten, wenn TypeScript in .astro-Frontmatter, Content-Collection-Schemas oder src/ verwendet wird.
• Verwendet es Content Collections? Überprüfen Sie auf src/content/config.ts oder src/content.config.ts. Wenn ja, validiert astro check die Schemas – besonders wertvoll.
• Hat es Tests? Überprüfen Sie auf tests/, __tests__/, *.test.ts oder vitest.config.ts. Wenn ja, richten Sie den Vitest-Workflow ein. Wenn nicht, erwähnen Sie, dass das Hinzufügen von Tests wertvoll wäre, aber erzwingen Sie es nicht.
• Welcher Paketmanager wird verwendet? Suchen Sie nach pnpm-lock.yaml, yarn.lock oder package-lock.json. Passen Sie den Installationsbefehl des Workflows an (pnpm i --frozen-lockfile, yarn install --frozen-lockfile oder npm ci).
• Wo wird deployed? Suchen Sie nach einer Datei wrangler.toml (Cloudflare), netlify.toml (Netlify), vercel.json (Vercel) oder fragen Sie einfach. Die meisten Hosts haben ihre eigene GitHub-App, die automatisch ohne Actions deployed – richten Sie einen Deploy-Workflow nur ein, wenn der Benutzer möchte, dass Actions dies übernimmt (typischerweise GitHub Pages oder selbst gehostet).
• Hat es einen Build-Schritt? Astro hat immer einen (astro build) – aber überprüfen Sie, ob das Skript in package.json das standardmäßige astro build und nicht etwas Eigenes ist.
• Ist es SSR oder statisch? Überprüfen Sie astro.config.* auf output: 'server' oder einen Adapter-Import. SSR-Projekte deployen anders (Cloudflare/Netlify/Vercel-Adapter) und sind möglicherweise überhaupt nicht auf GitHub Pages deploybar.

Schritt 2: Eine Reihe von Workflows empfehlen

Basierend auf Ihren Erkenntnissen empfehlen Sie, welche Workflows eingerichtet werden sollen. Eine gute Standardauswahl für die meisten Astro-Seiten:

• astro check (fast immer – dies ist der wertvollste Check für Astro)
• Build-Verifizierung (fast immer – fängt Integrationsregressionen auf, die astro check übersehen kann)
• ESLint + Prettier (wenn Konfigurationsdateien existieren oder der Benutzer sie möchte)
• Lighthouse CI (hervorragend für Content-Seiten mit öffentlichen URLs)
• Link-Checker (hervorragend für content-lastige Seiten)
• npm audit (günstig, fast immer lohnenswert)

Und bedingt:

• Vitest-Tests (wenn Tests existieren)
• Deploy-Workflow (nur wenn der Benutzer Actions-gesteuerte Deployments wünscht – die meisten Astro-Hosts verwenden ihre eigene GitHub-App)

Schritt 3: Die Workflow-Dateien erstellen

Erstellen Sie jeden Workflow als separate YAML-Datei in .github/workflows/. Die Verwendung separater Dateien anstelle eines monolithischen Workflows gibt klareres Feedback in Pull-Requests (jeder Check wird unabhängig angezeigt) und erleichtert das Aktivieren/Deaktivieren einzelner Checks.

Verwenden Sie die Vorlagen aus references/workflows.md als Ausgangspunkt, passen Sie sie jedoch an das jeweilige Projekt an. Übliche Anpassungen umfassen die Anpassung des Paketmanagers, der Node-Version, des Build-Artefakt-Pfads und des Deploy-Ziels.

Schritt 4: Unterstützende Konfigurationsdateien erstellen

Abhängig davon, welche Workflows Sie einrichten, benötigen Sie möglicherweise auch:

• eslint.config.js – ESLint-Flat-Config mit eslint-plugin-astro
• .prettierrc und .prettierignore – Prettier-Konfiguration mit prettier-plugin-astro
• lighthouserc.json – Lighthouse CI-Assertions
• lychee.toml – Link-Checker-Konfiguration (bei Verwendung von lychee)
• vitest.config.ts – Vitest-Konfiguration

Schritt 5: Erinnerung an Secrets

Wenn Sie einen Deploy-Workflow hinzufügen, erinnern Sie den Benutzer daran, welche Repository-Secrets benötigt werden:

• GitHub Pages – keines (verwendet GITHUB_TOKEN)
• Cloudflare Pages – CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
• Netlify – NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID
• Vercel – VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

Führen Sie sie durch: Repository-Einstellungen > Secrets and variables > Actions > Neues Repository-Secret.

Für Cloudflare, Netlify und Vercel: Erinnern Sie sie auch daran, dass diese Plattformen ihre eigenen GitHub-Apps ausliefern, die Build + Deploy + PR-Vorschauen automatisch handhaben. Actions-basierte Deployments lohnen sich normalerweise nur, wenn Sie das Deploy von Testergebnissen abhängig machen müssen, einen Build mit Secrets ausführen, die die Plattform nicht hat, oder von einem anderen Pfad als dem Repository-Root deployen möchten.

Namenskonventionen

Verwenden Sie beschreibende Workflow-Dateinamen, die sofort erkennen lassen, was jeder tut:

• astro-check.yml – astro check (Typ + Content-Schema)
• lint.yml – ESLint
• format.yml – Prettier-Check
• build.yml – Build-Verifizierung
• test.yml – Vitest
• lighthouse.yml – Lighthouse CI
• links.yml – Defekte Link-Prüfung
• security.yml – npm audit
• deploy.yml – Deploy zum Host

Wichtige Details

Node.js-Version: Astro benötigt Node 18.20.8+, 20.3.0+ oder 22.0.0+. Verwenden Sie Node 22 als Standard – es entspricht Astros stabilem Ziel, und viele Adapter werden dagegen getestet. Verwenden Sie actions/checkout@v5 und actions/setup-node@v5.

Paketmanager-Erkennung: Passen Sie immer die Lockfile an. pnpm-lock.yaml → pnpm/action-setup@v4 und pnpm install --frozen-lockfile. yarn.lock → yarn install --frozen-lockfile. package-lock.json → npm ci. Verwenden Sie npm install nicht in CI (nicht deterministisch, langsamer).

Branch-Namen: Die meisten Astro-Repos verwenden main als Standard-Branch, aber überprüfen Sie das tatsächliche Repository, bevor Sie Trigger schreiben.

Astro-Adapter und SSR: Wenn das Projekt @astrojs/cloudflare, @astrojs/netlify oder @astrojs/vercel verwendet, ist die Build-Ausgabe möglicherweise kein statisches dist/-Verzeichnis. Der Cloudflare-Adapter gibt dist/ plus eine _worker.js aus; Vercel gibt .vercel/output/ aus; Netlify gibt .netlify/ aus. Passen Sie die Deploy-Artefakt-Pfade entsprechend an.

astro check benötigt @astrojs/check und typescript: Beide müssen installiert sein. Wenn sie nicht in devDependencies sind, wird der Workflow fehlschlagen. Fügen Sie sie als Teil von npm ci nur hinzu, wenn sie bereits in package.json sind – andernfalls sollte der Workflow sie explizit installieren.

Lighthouse CI bei PRs: Die Ausführung von Lighthouse bei jedem PR fängt Performance-Regressionen frühzeitig ab. Die Aktion treosh/lighthouse-ci-action ist der Standard. Für eine öffentliche Vorschau-URL (Cloudflare Pages, Netlify, Vercel) richten Sie Lighthouse auf die Deploy-Preview-URL – das liefert realistische Zahlen. Für rein interne Setups bauen Sie die Seite und hosten Sie lokal im Runner.

Link-Checking auf gebauter Ausgabe, nicht auf Quelltext: Führen Sie den Link-Checker auf dem gebauten dist/-Verzeichnis (oder gegen eine Deploy-Preview-URL) aus – die Ausführung auf Markdown-Quellen übersieht generierte Routen und Sitemap-Links.

Bevorzugen Sie die GitHub-App der Plattform gegenüber Actions-Deployments: Cloudflare Pages, Netlify und Vercel haben alle erstklassige GitHub-Apps, die PR-Vorschauen, Branch-Deployments und Rollbacks besser handhaben als eine handgestrickte Action. Empfehlen Sie zuerst die GitHub-App; schlagen Sie ein Actions-Deployment nur vor, wenn der Benutzer einen bestimmten Grund hat, es auf diese Weise zu tun.