Déploiement
Déploiement • Chapitre 3 : Déploiement d'un site web statique

Déploiement sur GitHub Pages

Intégré au cœur de la plus grande plateforme de développement au monde, GitHub Pages vous permet d'héberger gratuitement vos sites web, portfolios et documentations directement depuis votre dépôt Git. Découvrez comment automatiser le build avec GitHub Actions et éviter les deux pièges célèbres : base-href et le fichier .nojekyll.

🐙
Hébergement Gratuit

Disponible gratuitement pour chaque compte et dépôt GitHub public, avec certificat SSL HTTPS inclus d'office.

⚙️
GitHub Actions

Automatisez le build (npm ci && npm run build) et la publication sur le CDN GitHub à chaque push.

📁
Le Piège .nojekyll

Un fichier vide indispensable pour empêcher le moteur Jekyll d'ignorer vos fichiers et dossiers commençant par un underscore.

🔤
Le Sous-Chemin Base

Le site vit dans /nom-du-depot/ : vos balises doivent être configurées avec base-href pour trouver les styles.

.github/workflows/deploy.yml
name: Déploiement automatique sur GitHub Pages

on:
  push:
    branches: [ main ] # Déclenché à chaque push sur la branche main

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 1. Récupération du code source
        uses: actions/checkout@v4

      - name: 2. Configuration de Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: 3. Installation et compilation propre
        run: |
          npm ci
          npm run build -- --base-href=/mon-depot/
          touch dist/.nojekyll

      - name: 4. Déploiement sur GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Les Deux Grands Pièges de GitHub Pages

1. Le Piège du Sous-Dossier (Base Href Trap)

Contrairement à Vercel où votre projet est servi à la racine absolue du domaine, l'URL GitHub Pages d'un projet prend la forme suivante :

https://<votre-pseudo>.github.io/mon-projet/

Si votre fichier index.html demande <link href="/styles.css"> (avec un slash initial), le navigateur va chercher le fichier sur https://<votre-pseudo>.github.io/styles.css, ce qui échouera avec une erreur 404 car le fichier se trouve dans le sous-dossier /mon-projet/styles.css !

Solution : Dans Angular, compilez toujours avec le flag : ng build --base-href=/nom-du-depot/.
Dans Vite, ajoutez base: '/nom-du-depot/' dans votre fichier vite.config.ts.

2. Le Mystère du fichier .nojekyll

À l'origine, GitHub Pages a été conçu pour faire fonctionner un générateur de blog en Ruby nommé Jekyll.

  • Par défaut, Jekyll ignore tous les fichiers et dossiers dont le nom commence par un underscore _ (comme _app/, _next/ ou _astro/).
  • Si vous déployez un framework moderne sans désactiver Jekyll, GitHub Pages supprimera silencieusement la moitié de vos fichiers JavaScript compilés !
Solution universelle : Créez simplement un fichier vide nommé .nojekyll à la racine du dossier publié (ex: touch dist/.nojekyll). Cela ordonne immédiatement à GitHub Pages de désactiver Jekyll et de servir les fichiers bruts.

3. Dépôt Utilisateur vs Dépôt Projet

GitHub distingue deux types de pages selon le nom de votre dépôt :

TypeNom du DépôtURL Publique RésultanteSous-dossier ?
Site Utilisateur Principalpseudo.github.iohttps://pseudo.github.io/Non (Racine)
Site de Projetportfolio ou mon-apphttps://pseudo.github.io/mon-app/Oui (Sous-chemin)

Tableau Comparatif : GitHub Pages vs Vercel vs Netlify

CritèreGitHub PagesVercelNetlify
Intégration Git100% Native (au cœur de GitHub)Via GitHub App WebhookVia GitHub App Webhook
Single Page Applications (SPA)Complexe (nécessite astuce 404.html)Natif (Rewrites automatiques)Natif (Fichier _redirects)
Sous-dossier d'URLOui (/nom-depot/)Non (Racine du sous-domaine)Non (Racine du sous-domaine)
Fonctions ServerlessImpossible (Statique pur uniquement)Oui (Serverless & Edge)Oui (Netlify Functions)