Échecs de build

Quand le builder statique échoue, le site ne tombe pas : votre build précédent continue de servir jusqu'à ce que vous corrigiez le problème et regénériez. Cette page explique où les échecs de build sont signalés, ce que signifient les différentes issues, et quoi tenter.

Où regarder

Deux endroits vous disent comment le dernier build s'est passé :

• Dashboard : panneau de statut de build. Il montre l'état courant sans détour : build en cours, l'heure du dernier build, Build Failed (avec "Last build exited with an error : site may be out of sync. Check build history below."), ou Promotion blocked quand un build a perdu trop de pages (la raison exacte du build lui-même est affichée).
• Build history. Les 100 derniers builds sont conservés avec leur sortie complète : chaque ligne montre OK, Error ou Blocked, l'horodatage, le nombre de fichiers écrits (ou le message d'échec), et le log de build complet dans une section dépliable.
• Une URL de statut de type /health répond aussi avec l'heure du dernier build et l'indication qu'un build est en cours, pour les moniteurs.

Les trois issues

• Error: le builder a rencontré des erreurs de rendu (par exemple un template cassé) et a refusé de promouvoir. La sortie de staging est jetée et la sortie précédente en production reste en place. Le message d'échec liste les templates défaillants, comme "page.tt for 'about'" (les premiers, puis le compte des autres).
• Blocked: le build est terminé, mais le builder l'a comparé au dernier bon build et a vu une chute trop grande (plus de 80 % des pages perdues) ou un pic de liens cassés ou de problèmes d'accessibilité, ce qui signifie généralement que le build était cassé même s'il a « réussi ». Le build précédent continue de servir : du contenu périmé, jamais du contenu cassé.
• OK: tout a été promu ; la ligne montre combien de fichiers ont été écrits plus le log complet.

Premières choses à tenter

• Rebuild complet. Un rebuild complet propre re-rend chaque page de zéro. Si un build incrémental semble avoir manqué vos changements, ceci vide le cache de build et regénère de zéro ; le bouton "Full rebuild" du dashboard fait cela (avec une confirmation ; il est plus lent que le défaut incrémental). La variable d'environnement d'urgence CHINASKI_FORCE_FULL=1 fait la même chose depuis un script d'ops.
• Promote anyway. Si un build a été bloqué mais que vous êtes sûr qu'il est correct, "Promote anyway" sur le dashboard le pousse en contournant la garde pour ce seul build. C'est une échapatoire ponctuelle : elle ne remet pas à zéro les mesures auxquelles la garde compare, et elle est censée rester un chemin inhabituel.
• Vérifiez l'endpoint de santé. C'est le moyen le plus rapide de voir si un problème d'environnement préexistant a causé l'échec : répertoire de sortie inscriptible, espace disque libre, fichier du builder présent, moteur de templates compile, etc.

Ce qui cause habituellement un build en échec

Les sources les plus courantes de messages d'échec sont :

• Erreurs de rendu de template: une page ou un bloc qui échoue à se rendre. Le message nomme les trois premiers templates défaillants.
• L'environnement de démarrage : exécuter le builder en root (il refuse), fichier de base manquant, ou script de build manquant.
• Plafonds de ressources atteints. Un build avorte quand il tente d'écrire plus que le budget d'écriture de 2 GiB ; chaque build a aussi une limite de temps mur de 30 minutes, passé cela le build est tué et la sortie précédente continue de servir.
• Signature du manifeste. Les builds signent leur manifeste de fichiers, et un build vert sans manifeste signé valide est traité comme un échec : la promotion avorte. Les environnements de test peuvent s'y soustraire avec un flag d'environnement.

Où vit le log une fois corrigé

Après un échec, les lignes dépliables de l'historique de build sont votre meilleur outil, la sortie complète du build en échec est là, prête à copier-coller dans un ticket de support, plus les comptes de templates défaillants pour cerner le problème.

Comptages de raisons et leurs effets

• Un build n'atteint l'étape de promotion que s'il y a zéro erreur de rendu. Toute erreur de rendu (ne serait-ce qu'une) bloque la promotion carrément.
• Les erreurs fatales (début de build) maintiennent le site en production en marche parce que le build précédent n'est pas remplacé après un échec.