Résolution des erreurs 404 pour les sites GitHub Pages

Ce guide vous aidera à résoudre les problèmes dus à des raisons courantes pour lesquelles vous pouvez voir une erreur 404.

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 ».

Résolution des erreurs 404

Dans ce guide, vous allez trouver des raisons courantes pour lesquelles vous pouvez voir une erreur 404 lors de la création de votre site GitHub Pages.

Page État de GitHub

Si vous voyez une erreur 404 lors de la création d’un site GitHub Pages, commencez par rechercher s’il y a des incidents actifs dans la page État de GitHub.

Configuration du DNS

Vérifiez que les enregistrements DNS de GitHub sont configurés correctement avec votre fournisseur DNS. Pour plus d’informations, consultez Gestion d’un domaine personnalisé pour votre site GitHub Pages.

Cache du navigateur

Si votre site GitHub Pages est privé et que vous voyez une erreur 404, il peut être nécessaire d’effacer le cache de votre navigateur. Pour plus d’informations sur l’effacement de votre cache, consultez la documentation de votre navigateur.

Fichier index.html

GitHub Pages va rechercher un fichier index.html comme fichier d’entrée pour votre site.

  • Vérifiez que vous disposez d’un fichier index.html dans le dépôt de votre site sur GitHub. Pour plus d’informations, consultez « Création d’un site GitHub Pages ».

  • Le fichier d’entrée doit se trouver au plus haut niveau de la source de publication choisie. Par exemple, si votre source de publication est le répertoire /docs de la branche main, votre fichier d’entrée doit se trouver dans le répertoire /docs sur une branche appelée main.

    Si votre source de publication est une branche et un répertoire, le fichier d’entrée doit être au plus haut niveau du répertoire source sur la branche source. Par exemple, si votre source de publication est le répertoire /docs de la branche main, votre fichier d’entrée doit se trouver dans le répertoire /docs sur une branche appelée main.

    Si votre source de publication est un workflow GitHub Actions, l’artefact que vous déployez doit inclure le fichier d’entrée au niveau supérieur de l’artefact. Au lieu d’ajouter le fichier d’entrée à votre dépôt, vous pouvez choisir de faire en sorte que votre workflow GitHub Actions génère votre fichier d’entrée quand il s’exécute.

  • Le nom du fichier index.html respecte la casse. Par exemple, Index.html ne va pas fonctionner.

  • Le nom du fichier doit être index.html, et non pas index.HTML ou une autre variante.

Contenu du répertoire

Vérifiez que le contenu de votre répertoire se trouve dans le répertoire racine.

Domaine personnalisé

Si vous utilisez un domaine personnalisé, vérifiez qu’il est configuré correctement. Pour plus d’informations, consultez « À propos des domaines personnalisés et des pages GitHub ».

  • L’enregistrement CNAME doit toujours pointer vers <USER>.github.io ou vers <ORGANIZATION>.github.io, à l’exclusion du nom du dépôt. Pour plus d’informations sur la création de l’enregistrement approprié, consultez la documentation de votre fournisseur DNS.
  • Si vous êtes en mesure d’accéder à votre page d’accueil, mais que vous rencontrez des liens rompus tout au long du processus, c’est probablement parce que vous n’aviez pas de nom de domaine personnalisé auparavant ou que vous revenez à un nom de domaine non personnalisé. Dans ce cas, la modification du chemin de routage ne lance pas une reconstruction de la page. La solution recommandée est de vérifier que votre site se reconstruit automatiquement lors de l’ajout ou de la suppression d’un nom de domaine personnalisé. Ceci peut impliquer la configuration d’un créateur de commit et la modification des paramètres de nom de domaine personnalisé.

Référentiel

Vérifiez si votre dépôt répond aux exigences suivantes.

  • La branche que vous utilisez pour publier votre site doit être main ou la branche par défaut.
  • Un commit doit être envoyé (push) au dépôt par une personne disposant d’autorisations d’administrateur pour le dépôt, comme le propriétaire du dépôt.
  • Le basculement de la visibilité du dépôt de public à privé, ou vice versa, change l’URL de votre site GitHub Pages, ce qui aboutit à des liens rompus jusqu’à ce que le site soit reconstruit.
  • Si vous utilisez un référentiel privé pour le site GitHub Pages, vérifiez si votre abonnement GitHub Pro, GitHub Team ou GitHub Enterprise Cloud est toujours actif. Si vous renouvelez le plan, le site GitHub Pages sera automatiquement redéployé. Sinon, vous pouvez modifier la visibilité de votre référentiel sur public pour continuer à utiliser GitHub Pages gratuitement.

Si vous recevez toujours une erreur 404, démarrez une discussion GitHub Community dans la catégorie Pages.