À propos des erreurs de build Jekyll pour les sites GitHub Pages

Si Jekyll rencontre une erreur lors de la génération de votre site GitHub Pages en local ou sur GitHub, vous recevez un message d’erreur avec davantage d’informations.

Qui peut utiliser cette fonctionnalité ?

GitHub Pages est disponible dans les référentiels publics avec GitHub Free et GitHub Free pour les organisations, et dans les référentiels publics et privés avec GitHub Pro, GitHub Team, GitHub Enterprise Cloud et GitHub Enterprise Server. Pour plus d’informations, consultez « Plans de GitHub ».

GitHub Pages utilise désormais GitHub Actions pour exécuter la version de Jekyll. Lorsque vous utilisez une branche comme source de votre version, GitHub Actions doit être activé dans votre référentiel si vous souhaitez utiliser le flux de travail Jekyll prédéfini. Comme alternative, si GitHub Actions n’est pas disponible ou désactivé, l’ajout d’un fichier .nojekyll à la racine de votre branche source contournera le processus de version de Jekyll et déploiera le contenu directement. Pour plus d'informations sur l'activation des GitHub Actions, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».

Dans cet article

À propos des erreurs de build Jekyll

Si vous publiez depuis une branche, parfois, GitHub Pages ne tente pas de générer votre site après avoir poussé les changements vers la source de publication de votre site.

  • La personne qui a poussé les changements n’a pas vérifié son adresse e-mail. Pour plus d’informations, consultez « Vérification de votre adresse e-mail ».
  • Vous poussez avec une clé de déploiement. Si vous souhaitez automatiser les poussées vers le dépôt de votre site, vous pouvez configurer un utilisateur d’ordinateur à la place. Pour plus d’informations, consultez « Gestion des clés de déploiement ».
  • Vous utilisez un service CI qui n’est pas configuré pour générer votre source de publication. Par exemple, Travis CI ne génère pas la branche gh-pages, sauf si vous ajoutez la branche à une liste sécurisée. Pour plus d’informations, consultez « Personnalisation de la build » sur Travis CI ou la documentation de votre service CI.

Remarque : La publication des changements de votre site peut prendre jusqu’à 10 minutes après les avoir poussés vers GitHub.

Si Jekyll tente de générer votre site et rencontre une erreur, vous recevez un message d’erreur de build.

Pour plus d’informations sur la résolution des erreurs de build, consultez « Résolution des erreurs de build Jekyll pour les sites GitHub Pages ».

Affichage des messages d’erreur de build Jekyll avec GitHub Actions

Par défaut, votre site GitHub Pages est généré et déployé avec l’exécution d’un workflow GitHub Actions, sauf si vous avez configuré votre site GitHub Pages pour utiliser un autre outil CI. Pour rechercher des erreurs de build potentielles, vous pouvez vérifier l’exécution du workflow pour votre site GitHub Pages en examinant les exécutions de workflow de votre dépôt. Pour plus d’informations, consultez « Affichage de l’historique des exécutions de workflows ». Pour plus d’informations sur la réexécutation du workflow en cas d’erreur, consultez « Ré-exécution de workflows et de travaux ».

Affichage des messages d’erreur de build Jekyll en local

Nous vous recommandons de tester votre site en local, ce qui vous permet de voir les messages d’erreur de build sur la ligne de commande et de corriger les échecs de build avant de pousser les changements vers GitHub. Pour plus d’informations, consultez « Test de votre site GitHub Pages localement avec Jekyll ».

Affichage des messages d’erreur de build Jekyll dans votre demande de tirage

Si vous publiez depuis une branche, lorsque vous créez une demande de tirage pour mettre à jour votre source de publication dans GitHub, vous pouvez voir les messages d’erreur de version sous l’onglet Vérifications de la demande de tirage. Pour plus d’informations, consultez « À propos des vérifications d’état ».

Si vous publiez avec un workflow GitHub Actions personnalisé afin de voir les messages d’erreur de version dans votre demande de tirage, vous devez configurer votre workflow pour qu’il s’exécute sur le déclencheur pull_request. Lorsque vous effectuez cette opération, nous vous recommandons d’ignorer les étapes de déploiement si le workflow a été déclenché par l’événement pull_request. Cela vous permet de voir les erreurs de build sans déployer les modifications de votre demande de tirage sur votre site. Pour plus d’informations, consultez « Événements qui déclenchent des flux de travail » et « Évaluer les expressions dans les workflows et les actions ».

Affichage des erreurs de build Jekyll par e-mail

Si vous publiez depuis une branche, lorsque vous publiez des changements vers votre source de publication dans GitHub, GitHub Pages tente de générer votre site. Si la build échoue, vous recevez un e-mail dans votre adresse e-mail principale.

Si vous publiez avec un workflow GitHub Actions personnalisé afin de recevoir les e-mails sur les erreurs de build dans votre demande de tirage, vous devez configurer votre workflow pour qu’il s’exécute sur le déclencheur pull_request. Lorsque vous effectuez cette opération, nous vous recommandons d’ignorer les étapes de déploiement si le workflow a été déclenché par l’événement pull_request. Cela vous permet de voir les erreurs de build sans déployer les modifications de votre demande de tirage sur votre site. Pour plus d’informations, consultez « Événements qui déclenchent des flux de travail » et « Évaluer les expressions dans les workflows et les actions ».

Affichage des messages d’erreur de build Jekyll dans votre demande de tirage avec un service CI tiers

Vous pouvez configurer un service tiers, tel que Travis CI, pour afficher les messages d’erreur après chaque commit.

  1. Si ce n’est déjà fait, ajoutez un fichier appelé Gemfile à la racine de votre source de publication, avec le contenu suivant :

    source `https://rubygems.org`
gem `github-pages`

  2. Configurez le dépôt de votre site pour le service de test de votre choix. Par exemple, pour utiliser Travis CI, ajoutez un fichier appelé .travis.yml à la racine de votre source de publication, avec le contenu suivant :

    language: ruby
rvm:
  - 2.3
script: "bundle exec jekyll build"

  3. Vous devrez peut-être activer votre dépôt avec le service de test tiers. Pour plus d’informations, consultez la documentation de votre service de test.