Actions GitHub pour Astro

Que fait Actions GitHub pour Astro ?

Cette compétence vous aide à configurer un pipeline CI/CD complet pour les sites Astro en utilisant GitHub Actions. L'objectif est d'aider les auteurs à livrer des sites de meilleure qualité avec moins d'effort manuel : les erreurs de type sont détectées avant la fusion, les liens cassés sont signalés, les builds sont vérifiés et les déploiements sont automatisés.

Ce que couvre cette compétence

Il existe plusieurs catégories de workflows qu'un projet Astro sain devrait avoir. Tous les sites n'ont pas besoin de tous ces workflows — la bonne combinaison dépend du fait que le projet utilise TypeScript, des composants personnalisés, des collections de contenu, des tests, et de sa cible de déploiement. Votre travail consiste à déterminer lesquels sont pertinents et à les mettre en place.

Les workflows se répartissent dans ces catégories :

1. Vérification des types/contenu — astro check (TypeScript + validation des schémas de collection de contenu)
2. Qualité du code — ESLint et Prettier
3. Vérification du build — astro build s'exécute correctement
4. Tests — Vitest pour les tests unitaires et de composants
5. Contrôles qualité — Lighthouse CI (performances, accessibilité, SEO, bonnes pratiques)
6. Vérification des liens — Détection des liens cassés sur le site construit
7. Sécurité — npm audit pour les vulnérabilités des dépendances
8. Déploiement — GitHub Pages, Cloudflare Pages, Netlify ou Vercel

Consultez references/workflows.md pour la configuration détaillée de chaque workflow, y compris les modèles YAML prêts à l'emploi et les fichiers de configuration.

Comment aborder une demande

Étape 1 : Comprendre le projet

Avant d'écrire des fichiers de workflow, déterminez avec quoi vous travaillez :

• Est-ce du TypeScript ? Vérifiez la présence de tsconfig.json et de fichiers .ts/.astro. Presque tous les projets Astro devraient exécuter astro check, mais la valeur est maximale lorsqu'il y a du TypeScript dans le frontmatter .astro, les schémas de collections de contenu ou src/.
• Utilise-t-il des collections de contenu ? Vérifiez la présence de src/content/config.ts ou src/content.config.ts. Si oui, astro check valide les schémas — c'est très utile.
• A-t-il des tests ? Vérifiez la présence de tests/, __tests__/, *.test.ts ou vitest.config.ts. Si oui, configurez le workflow Vitest. Sinon, mentionnez que l'ajout de tests serait utile, mais n'insistez pas.
• Quel est le gestionnaire de paquets ? Recherchez pnpm-lock.yaml, yarn.lock ou package-lock.json. Adaptez la commande d'installation du workflow (pnpm i --frozen-lockfile, yarn install --frozen-lockfile ou npm ci).
• Où déploie-t-il ? Recherchez un fichier wrangler.toml (Cloudflare), netlify.toml (Netlify), vercel.json (Vercel), ou demandez simplement. La plupart des hébergeurs ont leur propre application GitHub qui déploie automatiquement sans Actions — ne configurez un workflow de déploiement que si l'utilisateur souhaite vraiment qu'Actions s'en charge (typiquement GitHub Pages ou hébergement auto-géré).
• A-t-il une étape de build ? Astro en a toujours une (astro build) — mais vérifiez que le script dans package.json est le astro build standard et non quelque chose de personnalisé.
• Est-ce SSR ou statique ? Vérifiez astro.config.* pour une option output: 'server' ou une importation d'adaptateur. Les projets SSR se déploient différemment (adaptateurs Cloudflare/Netlify/Vercel) et peuvent ne pas être déployables sur GitHub Pages du tout.

Étape 2 : Recommander un ensemble de workflows

Sur la base de ce que vous avez trouvé, recommandez les workflows à configurer. Une bonne configuration par défaut pour la plupart des sites Astro :

• astro check (presque toujours — c'est la vérification la plus précieuse pour Astro)
• Vérification du build (presque toujours — attrape les régressions d'intégration que astro check peut manquer)
• ESLint + Prettier (si les fichiers de configuration existent ou que l'utilisateur les souhaite)
• Lighthouse CI (excellent pour les sites de contenu avec des URL publiques)
• Vérificateur de liens (excellent pour les sites riches en contenu)
• npm audit (peu coûteux, presque toujours intéressant)

Et conditionnellement :

• Tests Vitest (si des tests existent)
• Workflow de déploiement (uniquement si l'utilisateur souhaite des déploiements pilotés par Actions — la plupart des hébergeurs Astro utilisent leur propre application GitHub)

Étape 3 : Créer les fichiers de workflow

Créez chaque workflow sous forme de fichier YAML séparé dans .github/workflows/. Utiliser des fichiers séparés plutôt qu'un seul workflow monolithique offre un retour plus clair dans les PR (chaque vérification s'affiche indépendamment) et facilite l'activation/désactivation des vérifications individuelles.

Utilisez les modèles de references/workflows.md comme points de départ, mais adaptez-les au projet spécifique. Les adaptations courantes incluent l'ajustement du gestionnaire de paquets, de la version de Node, du chemin de l'artefact de build et de la cible de déploiement.

Étape 4 : Créer les fichiers de configuration associés

Selon les workflows que vous configurez, vous pourriez également avoir besoin de :

• eslint.config.js — Configuration plate d'ESLint avec eslint-plugin-astro
• .prettierrc et .prettierignore — Configuration Prettier avec prettier-plugin-astro
• lighthouserc.json — Assertions Lighthouse CI
• lychee.toml — Configuration du vérificateur de liens (si vous utilisez lychee)
• vitest.config.ts — Configuration Vitest

Étape 5 : Rappel des secrets

Si vous ajoutez un workflow de déploiement, rappelez à l'utilisateur quels secrets de dépôt sont nécessaires :

• GitHub Pages — aucun (utilise 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

Guide-les : Paramètres du dépôt > Secrets et variables > Actions > Nouveau secret de dépôt.

Pour Cloudflare, Netlify et Vercel : rappelez-leur également que ces plateformes fournissent leurs propres applications GitHub qui gèrent automatiquement le build + déploiement + prévisualisations des PR. Les déploiements basés sur Actions ne valent généralement la peine que lorsque vous devez conditionner le déploiement aux résultats des tests, exécuter un build avec des secrets que la plateforme ne possède pas, ou déployer depuis un chemin autre que la racine du dépôt.

Conventions de nommage

Utilisez des noms de fichiers de workflow descriptifs qui indiquent clairement ce que chacun fait :

• astro-check.yml — astro check (type + schéma de contenu)
• lint.yml — ESLint
• format.yml — Vérification Prettier
• build.yml — Vérification du build
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — Vérificateur de liens cassés
• security.yml — npm audit
• deploy.yml — Déploiement vers l'hébergeur

Détails importants

Version de Node.js : Astro nécessite Node 18.20.8+, 20.3.0+ ou 22.0.0+. Utilisez Node 22 par défaut — cela correspond à la cible stable d'Astro et de nombreux adaptateurs sont testés avec cette version. Utilisez actions/checkout@v5 et actions/setup-node@v5.

Détection du gestionnaire de paquets : Faites toujours correspondre le fichier de verrouillage. pnpm-lock.yaml → utilisez pnpm/action-setup@v4 et pnpm install --frozen-lockfile. yarn.lock → yarn install --frozen-lockfile. package-lock.json → npm ci. N'utilisez pas npm install dans CI (non déterministe, plus lent).

Nommage des branches : La plupart des dépôts Astro utilisent main comme branche par défaut, mais vérifiez le dépôt réel avant d'écrire les déclencheurs.

Adaptateurs Astro et SSR : Si le projet utilise @astrojs/cloudflare, @astrojs/netlify ou @astrojs/vercel, le résultat du build peut ne pas être un simple répertoire statique dist/. L'adaptateur Cloudflare génère dist/ plus un fichier _worker.js ; Vercel génère .vercel/output/ ; Netlify génère .netlify/. Ajustez les chemins des artefacts de déploiement en conséquence.

astro check nécessite @astrojs/check et typescript : Les deux doivent être installés. S'ils ne figurent pas dans devDependencies, le workflow échouera. Ajoutez-les dans le cadre de npm ci uniquement s'ils sont déjà dans package.json — sinon le workflow doit les installer explicitement.

Lighthouse CI sur les PR : Exécuter Lighthouse sur chaque PR permet de détecter tôt les régressions de performances. L'action treosh/lighthouse-ci-action est la référence. Pour une URL d'aperçu public (Cloudflare Pages, Netlify, Vercel), pointez Lighthouse vers l'URL d'aperçu du déploiement — cela donne des chiffres réalistes. Pour les configurations internes uniquement, construisez et servez localement dans le runner.

Vérification des liens sur la sortie du build, pas sur la source : Exécutez le vérificateur de liens sur le répertoire dist/ construit (ou sur une URL d'aperçu déployée) — l'exécuter sur la source Markdown manque les routes générées et les liens du plan du site.

Préférez l'application GitHub de la plateforme aux déploiements Actions : Cloudflare Pages, Netlify et Vercel ont tous des applications GitHub officielles qui gèrent les prévisualisations des PR, les déploiements de branches et les restaurations mieux qu'une Action faite maison. Recommandez d'abord l'application GitHub ; ne suggérez un déploiement Actions que lorsque l'utilisateur a une raison spécifique de le faire de cette façon.