# GitHub Pages : hébergement gratuit de votre site, publication pas à pas

URL: https://skillaria.top/fr/guides/git/github-pages-publier-site-gratuit

GitHub Pages est un hébergement gratuit de sites statiques directement depuis un dépôt GitHub. Vous déposez HTML, CSS et JavaScript dans le dépôt, activez Pages dans les paramètres, et le site est accessible à une adresse du type username.github.io ; un domaine personnalisé et HTTPS sont possibles, mais le code serveur comme PHP ou les bases de données n'est pas pris en charge.

## Qu'est-ce que GitHub Pages

GitHub Pages est un hébergement gratuit de sites statiques, intégré à GitHub. Vous conservez les fichiers du site dans un dépôt Git ordinaire, et GitHub les diffuse en HTTPS. Chaque nouveau `git push` sur la bonne branche met le site à jour : pas besoin de FTP, de panneau d'hébergement ni de téléversement manuel.

On parle en français de « GitHub Pages », ou simplement de « Pages ». Une question fréquente est « git pages c'est quoi » : il faut savoir que GitHub Pages est une fonctionnalité de la plateforme GitHub, et non de Git lui-même. Git ne publie rien, il conserve seulement l'historique des modifications.

On utilise surtout GitHub Pages pour la documentation de projets, les pages personnelles et les portfolios, les blogs, les landing pages, les projets d'apprentissage et les démos d'applications front-end (React, Vue, Svelte) une fois compilées.

### Git Pages est un hébergement de contenu statique

Le mot clé est statique. GitHub Pages délivre au navigateur des fichiers déjà prêts : HTML, CSS, JavaScript, images, polices, JSON. Il n'exécute pas de code côté serveur : PHP, Python ou Node.js côté serveur, et les bases de données ne fonctionnent pas ici. Si votre site a besoin d'une inscription, d'un panier ou d'une administration avec base de données, il vous faut un hébergement classique ou une plateforme cloud.

En revanche, le JavaScript s'exécute dans le navigateur comme d'habitude. Une application monopage peut interroger des API externes, les formulaires peuvent être envoyés via des services tiers, et la recherche sur le site peut être faite côté client.

## Les types de sites sur GitHub Pages

GitHub Pages propose trois types de sites, et le type détermine l'adresse.

| Type | Dépôt | Adresse |
| --- | --- | --- |

| Site d'utilisateur | `username.github.io` | `https://username.github.io/` |

| Site d'organisation | `orgname.github.io` | `https://orgname.github.io/` |

| Site de projet | nom quelconque, par exemple `docs` | `https://username.github.io/docs/` |

Il ne peut y avoir qu'un seul site d'utilisateur ou d'organisation par compte, alors que les sites de projet sont illimités, à raison d'un par dépôt. Le nom du dépôt du site personnel doit correspondre exactement à votre identifiant GitHub : si votre identifiant est `ivan-petrov`, le dépôt s'appelle `ivan-petrov.github.io`.

Pour les dépôts publics, Pages est disponible dans l'offre gratuite. Publier un site à partir d'un dépôt privé nécessite une offre payante de GitHub ; le site publié reste toutefois visible de tous sur Internet.

## Publier un site sur GitHub Pages pas à pas

Voyons la méthode la plus simple : des fichiers HTML prêts à l'emploi, publiés depuis une branche. Il vous faut un compte GitHub et Git installé.

### Étape 1. Créer le dépôt

Sur GitHub, créez un nouveau dépôt public. Pour un site personnel, nommez-le `username.github.io` ; pour un site de projet, le nom est libre. Clonez-le ensuite et ajoutez la page d'accueil :

```
git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "

# Bonjour, GitHub Pages

" > index.html
```

La page d'accueil doit impérativement s'appeler `index.html` (ou `index.md`, ou `README.md` : GitHub en fera aussi la page d'accueil). La casse compte : `Index.html` ne fonctionnera pas.

### Étape 2. Envoyer les fichiers sur GitHub

```
git add index.html
git commit -m "Première page du site"
git push origin main
```

Si Git demande un identifiant et un mot de passe lors du premier envoi, utilisez un token d'accès personnel ou la connexion par navigateur : le mot de passe habituel du compte GitHub n'est plus accepté par `git push` en HTTPS.

### Étape 3. Activer Pages dans les paramètres

Ouvrez le dépôt sur GitHub, allez dans Settings puis choisissez Pages dans le menu latéral. Dans le bloc Build and deployment, sélectionnez Deploy from a branch dans le champ Source. Indiquez ensuite la branche (en général `main`) et le dossier : la racine `/ (root)` ou `/docs`. Cliquez sur Save.

Le dossier `/docs` est pratique lorsque le dépôt contient le code du projet et que le site de documentation se trouve à côté, dans un répertoire séparé.

### Étape 4. Attendre la publication

La publication prend de quelques secondes à quelques minutes ; GitHub prévient que la première peut durer jusqu'à 10 minutes. La progression apparaît dans l'onglet Actions, sous le nom pages build and deployment. Une fois le processus terminé avec une coche verte, l'adresse du site s'affiche dans Settings → Pages.

Ensuite, tout est simple : vous modifiez les fichiers, faites un commit et un `git push`, et le site se met à jour automatiquement.

## Publication avec GitHub Actions

La publication depuis une branche convient lorsque le dépôt contient des fichiers prêts à l'emploi. Si le site doit d'abord être compilé, par exemple une application Vite, React ou un générateur comme Hugo, la source GitHub Actions est plus adaptée. Dans Settings → Pages, choisissez GitHub Actions dans le champ Source : GitHub propose alors des modèles de workflow prêts à l'emploi.

Voici un workflow minimal pour publier les fichiers statiques du dossier `dist` après la compilation :

```
name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4
```

Le fichier se place dans `.github/workflows/pages.yml`. Après le `git push`, Actions installe les dépendances, compile le projet et publie le contenu de `dist`. L'avantage : le dépôt ne contient que le code source, et les fichiers compilés n'encombrent pas l'historique des commits.

Un piège courant sur les sites de projet concerne les chemins. Le site est accessible à l'adresse `/nom-du-dépôt/`, mais le compilateur fait par défaut référence aux ressources depuis la racine `/`. La page se charge alors sans styles ni scripts. La solution consiste à définir le chemin de base : dans Vite, le paramètre `base: '/nom-du-dépôt/'`, et une option équivalente dans les autres outils.

## Jekyll et les générateurs de sites statiques

Lors d'une publication depuis une branche, GitHub fait passer les fichiers par Jekyll, un générateur de sites statiques écrit en Ruby. Vous pouvez donc rédiger des pages en Markdown, utiliser des thèmes et des modèles, et GitHub les transforme en HTML. Pour un blog ou une documentation, c'est commode : vous écrivez des fichiers `.md`, et le thème s'occupe de la mise en forme.

Effet secondaire : Jekyll ignore les fichiers et dossiers dont le nom commence par un tiret bas, comme `_next` ou `_assets`. Si le site a été généré par un autre outil et que ces dossiers sont nécessaires, placez à la racine un fichier vide `.nojekyll` :

```
touch .nojekyll
git add .nojekyll
git commit -m "Désactiver Jekyll"
git push
```

Les autres générateurs (Hugo, Astro, Eleventy, MkDocs, Docusaurus) fonctionnent via GitHub Actions : la compilation a lieu dans le workflow et le dossier final est publié. GitHub Pages ne connaît pas ces outils ; il lui suffit des fichiers finaux.

## Relier un domaine personnalisé à GitHub Pages

L'adresse `username.github.io` convient aux projets d'apprentissage, mais pour un portfolio ou un projet professionnel, un domaine personnalisé est préférable. La liaison se fait dans deux sens : chez le bureau d'enregistrement du domaine, et dans les paramètres du dépôt.

### Configurer le DNS

Pour un sous-domaine comme `www.example.com` ou `blog.example.com`, créez un enregistrement CNAME pointant vers `username.github.io`. Pour le domaine principal `example.com`, créez des enregistrements A vers les adresses IP de GitHub Pages :

```
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
```

La liste à jour des adresses, y compris l'IPv6 pour les enregistrements AAAA, figure dans la documentation de GitHub : vérifiez-la avant de configurer. Il est préférable de configurer à la fois le domaine principal et `www` : GitHub redirigera alors l'une des adresses vers l'autre.

### Réglage dans le dépôt

Dans Settings → Pages, saisissez le domaine dans le champ Custom domain et enregistrez. Lors d'une publication depuis une branche, GitHub crée dans le dépôt un fichier `CNAME` portant le nom du domaine. Avec une publication via Actions, le fichier `CNAME` n'est pas nécessaire : le domaine est conservé dans les paramètres.

GitHub recommande de vérifier le domaine dans les paramètres du compte (section Pages des paramètres de profil) : cela empêche qu'une autre personne rattache votre domaine à son propre dépôt pendant que le DNS pointe vers GitHub. Les modifications DNS peuvent prendre jusqu'à une journée pour se propager ; si le domaine ne fonctionne pas tout de suite, patientez.

## HTTPS sur GitHub Pages

Pour les adresses `*.github.io`, HTTPS est toujours activé. Pour votre propre domaine, GitHub délivre lui-même un certificat Let's Encrypt dès que le DNS est correctement configuré. Une case Enforce HTTPS apparaît alors dans Settings → Pages : cochez-la pour que toutes les requêtes HTTP soient redirigées vers HTTPS.

Si la case est inactive, c'est que le certificat n'est pas encore émis : vérifiez les enregistrements DNS et patientez. Il arrive que retirer le domaine du champ Custom domain puis le saisir à nouveau aide, car cela relance l'émission du certificat. Vérifiez aussi que le site ne charge pas d'images ni de scripts en `http://` : le navigateur bloquerait ces ressources comme contenu mixte.

## Limites de GitHub Pages

L'hébergement est gratuit, mais il a des limites. Elles sont décrites dans la documentation de GitHub, et pour la plupart des sites personnels et d'apprentissage, elles sont largement suffisantes.

| Limite | Valeur |
| --- | --- |

| Contenu | uniquement des fichiers statiques, sans code serveur ni base de données |

| Taille du site publié | jusqu'à 1 Go |

| Taille recommandée du dépôt | jusqu'à 1 Go |

| Trafic | limite indicative de 100 Go par mois |

| Compilations depuis une branche | limite indicative de 10 par heure (sans objet pour Actions) |

| Durée de publication | un déploiement de plus de 10 minutes est interrompu |

Au-delà des limites techniques, des règles d'utilisation s'appliquent : GitHub Pages n'est pas destiné aux services commerciaux comme les boutiques en ligne ou les SaaS, ni à la diffusion de gros fichiers. Pour les portfolios, la documentation, les blogs et les landing pages de projets, il convient parfaitement.

Autre limite : il n'existe pas de configuration serveur. Pas de redirections personnalisées, pas d'en-têtes de réponse, pas de règles de type `.htaccess`. Vous pouvez seulement placer une page `404.html` personnalisée à la racine : GitHub l'affichera pour les adresses inexistantes.

## Problèmes courants et solutions

### Erreur 404 sur GitHub Pages

La cause la plus fréquente : il n'existe pas de fichier `index.html` dans le dossier choisi comme source. Vérifiez que vous avez sélectionné la bonne branche et le bon dossier (`/ (root)` ou `/docs`), et que le fichier s'appelle bien `index.html` en minuscules. Deuxième cause : le site n'est pas encore publié. Consultez l'onglet Actions et attendez la fin de la compilation.

Si l'erreur 404 apparaît sur les pages internes d'une application monopage lors d'un rechargement, le problème vient du routage : le serveur ne connaît pas l'adresse `/about`, car ce fichier n'existe pas. Vous pouvez contourner le problème avec un routage par fragment (`/#/about`) ou en copiant `index.html` sous le nom `404.html`.

### Le site ne se met pas à jour

Commencez par vérifier que les modifications sont bien arrivées sur GitHub : exécutez `git status` et `git log origin/main --oneline -3`. Ouvrez ensuite l'onglet Actions : si la compilation a échoué, une croix rouge et un journal indiquent l'erreur, par exemple une syntaxe incorrecte dans un fichier Jekyll ou une erreur dans le workflow.

Si la compilation a réussi mais que le navigateur affiche une ancienne version, c'est le cache. GitHub Pages met les fichiers en cache pendant quelques minutes, et le navigateur fait de même. Rechargez la page en vidant le cache (Ctrl+F5 ou Cmd+Maj+R) ou ouvrez-la dans une fenêtre de navigation privée.

### Les styles et les images ne se chargent pas

Presque toujours, les chemins sont incorrects. Sur un site de projet, le lien `/style.css` pointe vers la racine de `username.github.io` et non vers le dossier du dépôt. Utilisez des chemins relatifs (`style.css`, `./img/logo.png`) ou définissez le chemin de base dans l'outil de compilation. Vérifiez aussi la casse : les serveurs de GitHub distinguent `Logo.PNG` de `logo.png`, même si tout fonctionnait en local sous Windows.

### Des dossiers commençant par un tiret bas disparaissent

C'est Jekyll : il ne publie pas les répertoires comme `_app`. Ajoutez à la racine le fichier `.nojekyll` ou passez à une publication via GitHub Actions.

## Conclusion

GitHub Pages est le moyen le plus rapide de publier gratuitement un site statique : un dépôt, un fichier `index.html`, une source définie dans Settings → Pages, et en quelques minutes le site est accessible à l'adresse `username.github.io`. Pour les sites nécessitant une compilation, utilisez GitHub Actions ; pour un domaine personnalisé, configurez les enregistrements DNS et cochez Enforce HTTPS. Gardez à l'esprit les limites : contenu statique uniquement, sans code serveur, avec des plafonds de taille et de trafic. La pratique de GitHub, l'envoi des modifications et l'automatisation sont abordés en pratique dans le cours sur Git.

## FAQ

**GitHub Pages est-il vraiment gratuit ?**

Oui, pour les dépôts publics dans l'offre gratuite, GitHub Pages ne coûte rien, y compris HTTPS et un domaine personnalisé. Vous ne payez que le nom de domaine auprès de votre registrar, et éventuellement une offre payante de GitHub si vous voulez publier depuis un dépôt privé.

**Peut-on héberger un site PHP ou WordPress sur GitHub Pages ?**

Non, GitHub Pages ne sert que des fichiers statiques et n'exécute pas de code serveur. Un site WordPress peut être exporté en HTML statique à l'aide de certaines extensions, mais les formulaires, les commentaires et l'administration ne fonctionneront plus.

**Combien de sites peut-on créer sur GitHub Pages ?**

Un site d'utilisateur à l'adresse username.github.io et un nombre illimité de sites de projet, à raison d'un par dépôt.

**Les moteurs de recherche indexent-ils les sites GitHub Pages ?**

Oui, ces sites sont indexés comme les autres. Pour une meilleure indexation, ajoutez les fichiers sitemap.xml et robots.txt à la racine et validez le site dans les outils pour webmasters des moteurs de recherche.

**Comment supprimer un site de GitHub Pages ?**

Dans Settings → Pages, cliquez sur Unpublish site si ce bouton est disponible, ou choisissez la valeur None dans le champ Source pour la branche. La suppression du dépôt retire elle aussi le site.


---
Source: Skillaria.Top (https://skillaria.top)