netlify-deploy

--- Déployer des projets web sur Netlify en utilisant la CLI Netlify (`npx netlify`). À utiliser quand l'utilisateur demande de déployer, héberger, publier ou lier un site/repo sur Netlify, y compris les déploiements en aperçu et en production.

npx skills add https://github.com/openai/skills --skill netlify-deploy

Compétence de déploiement Netlify

Déployer des projets web sur Netlify à l'aide de Netlify CLI avec détection intelligente de la configuration du projet et du contexte de déploiement.

Aperçu

Cette compétence automatise les déploiements Netlify en :

  • Vérifiant l'authentification Netlify CLI
  • Détectant la configuration du projet et le framework
  • Liant à des sites existants ou en créant de nouveaux
  • Déployant vers des environnements de production ou d'aperçu

Prérequis

  • Netlify CLI : Installée via npx (aucune installation globale requise)
  • Authentification : Compte Netlify avec session de connexion active
  • Projet : Projet web valide dans le répertoire courant
  • Lorsque le sandboxing bloque les appels réseau de déploiement, relancez avec sandbox_permissions=require_escalated.
  • Le déploiement peut prendre quelques minutes. Utilisez des valeurs de timeout appropriées.

Modèle d'authentification

La compétence utilise l'approche Netlify CLI pré-authentifiée :

  1. Vérifier l'état d'authentification avec npx netlify status
  2. Si non authentifié, guider l'utilisateur via npx netlify login
  3. Échouer gracieusement si l'authentification ne peut pas être établie

L'authentification utilise soit :

  • OAuth basé sur le navigateur (principal) : netlify login ouvre un navigateur pour l'authentification
  • Clé API (alternative) : Définir la variable d'environnement NETLIFY_AUTH_TOKEN

Flux de travail

1. Vérifier l'authentification Netlify CLI

Vérifier si l'utilisateur est connecté à Netlify :

npx netlify status

Modèles de sortie attendus :

  • ✅ Authentifié : Affiche l'e-mail de l'utilisateur connecté et l'état du lien du site
  • ❌ Non authentifié : « Not logged into any site » ou erreur d'authentification

Si non authentifié, guider l'utilisateur :

npx netlify login

Cela ouvre une fenêtre de navigateur pour l'authentification OAuth. Attendez que l'utilisateur termine la connexion, puis vérifiez avec netlify status à nouveau.

Alternative : authentification par clé API

Si l'authentification par navigateur n'est pas disponible, les utilisateurs peuvent définir :

export NETLIFY_AUTH_TOKEN=your_token_here

Les jetons peuvent être générés sur : https://app.netlify.com/user/applications#personal-access-tokens

2. Détecter l'état du lien du site

À partir de la sortie netlify status, déterminer :

  • Lié : Site déjà connecté à Netlify (affiche le nom/URL du site)
  • Non lié : Besoin de lier ou créer un site

3. Lier à un site existant ou créer un nouveau

Si déjà lié → Passer à l'étape 4

Si non lié, tenter de lier par la télécommande Git :

# Vérifier si le projet est basé sur Git
git remote show origin

# Si basé sur Git, extraire l'URL de la télécommande
# Format : https://github.com/username/repo ou git@github.com:username/repo.git

# Essayer de lier par la télécommande Git
npx netlify link --git-remote-url <REMOTE_URL>

Si le lien échoue (le site n'existe pas sur Netlify) :

# Créer un nouveau site de façon interactive
npx netlify init

Cela guide l'utilisateur à travers :

  1. Choisir l'équipe/compte
  2. Définir le nom du site
  3. Configurer les paramètres de build
  4. Créer netlify.toml si nécessaire

4. Vérifier les dépendances

Avant de déployer, s'assurer que les dépendances du projet sont installées :

# Pour les projets npm
npm install

# Pour d'autres gestionnaires de paquets, détecter et utiliser la commande appropriée
# yarn install, pnpm install, etc.

5. Déployer sur Netlify

Choisir le type de déploiement en fonction du contexte :

Déploiement d'aperçu/brouillon (par défaut pour les sites existants) :

npx netlify deploy

Cela crée un aperçu de déploiement avec une URL unique pour les tests.

Déploiement en production (pour les nouveaux sites ou les déploiements de production explicites) :

npx netlify deploy --prod

Cela déploie vers l'URL de production en direct.

Processus de déploiement :

  1. CLI détecte les paramètres de build (depuis netlify.toml ou demande à l'utilisateur)
  2. Construit le projet localement
  3. Charge les actifs construits sur Netlify
  4. Retourne l'URL de déploiement

6. Signaler les résultats

Après le déploiement, signaler à l'utilisateur :

  • URL de déploiement : URL unique pour ce déploiement
  • URL du site : URL de production (si déploiement en production)
  • Journaux de déploiement : Lien vers le tableau de bord Netlify pour les journaux
  • Prochaines étapes : Suggérer netlify open pour voir le site ou le tableau de bord

Gestion de netlify.toml

Si un fichier netlify.toml existe, le CLI l'utilise automatiquement. Sinon, le CLI demandera :

  • Commande de build : par exemple, npm run build, next build
  • Répertoire de publication : par exemple, dist, build, .next

Valeurs par défaut courantes des frameworks :

  • Next.js : commande de build npm run build, publication .next
  • React (Vite) : commande de build npm run build, publication dist
  • HTML statique : pas de commande de build, publication du répertoire courant

La compétence doit détecter le framework depuis package.json si possible et suggérer les paramètres appropriés.

Exemple de flux de travail complet

# 1. Vérifier l'authentification
npx netlify status

# Si non authentifié :
npx netlify login

# 2. Lier le site (si nécessaire)
# Essayer d'abord le lien basé sur Git
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo

# Si aucun site n'existe, créer un nouveau :
npx netlify init

# 3. Installer les dépendances
npm install

# 4. Déployer (aperçu pour les tests)
npx netlify deploy

# 5. Déployer en production (quand prêt)
npx netlify deploy --prod

Gestion des erreurs

Problèmes courants et solutions :

« Not logged in » → Exécuter npx netlify login

« No site linked » → Exécuter npx netlify link ou npx netlify init

« Build failed » → Vérifier la commande de build et le répertoire de publication dans netlify.toml ou les invites CLI → Vérifier que les dépendances sont installées → Examiner les journaux de build pour les erreurs spécifiques

« Publish directory not found » → Vérifier que la commande de build s'est exécutée avec succès → Vérifier que le chemin du répertoire de publication est correct

Dépannage

Accès réseau élevé

Si le déploiement échoue en raison de problèmes réseau (délais d'expiration, erreurs DNS, réinitialisations de connexion), relancez le déploiement avec des permissions élevées (utiliser sandbox_permissions=require_escalated). Le déploiement nécessite un accès réseau élevé lorsque la mise en réseau du sandbox bloque les demandes sortantes.

Exemple de conseils pour l'utilisateur :

Le déploiement a besoin d'un accès réseau élevé pour déployer sur Netlify. Je peux relancer la commande avec des permissions élevées—voulez-vous que je procède ?

Variables d'environnement

Pour les secrets et la configuration :

  1. Ne jamais valider les secrets dans Git
  2. Définir dans le tableau de bord Netlify : Site Settings → Environment Variables
  3. Accéder dans les builds via process.env.VARIABLE_NAME

Conseils

  • Utiliser netlify deploy (sans --prod) d'abord pour tester avant la production
  • Exécuter netlify open pour voir le site dans le tableau de bord Netlify
  • Exécuter netlify logs pour voir les journaux des fonctions (si vous utilisez Netlify Functions)
  • Utiliser netlify dev pour le développement local avec Netlify Functions

Référence

Références regroupées (charger selon les besoins)