Héberger son site avec GitHub Pages

Votre agent vient de générer une belle petite application web. Elle tourne sur votre ordinateur en tapant npm run dev. Super. Mais comment la montrer à votre collègue, à un client, ou à votre maman ?

C’est là qu’intervient l’hébergement : mettre votre site sur un serveur accessible depuis Internet, avec une vraie adresse web (une URL). Et GitHub propose un service gratuit pour ça, qui s’appelle GitHub Pages.

C’est quoi GitHub Pages, concrètement ?

Imaginez que GitHub vous prête un petit bout de serveur, gratuitement. Vous y déposez les fichiers de votre site (du HTML, du CSS, des images, du JavaScript), et GitHub les rend accessibles à tout le monde via une adresse web.

L’adresse par défaut ressemble à :

https://votre-pseudo.github.io/nom-du-projet/

C’est déjà très bien pour démarrer. Et si vous voulez un vrai domaine genre monsuperprojet.com, c’est possible aussi (on en parle plus loin).

💡 Tout (ou presque) peut être demandé à l’agent

La plupart des étapes de ce chapitre peuvent être réalisées directement par votre agent de code (Claude Code, Cursor, Copilot CLI…) s’il a accès à l’outil gh — la ligne de commande officielle de GitHub. Vérifiez avec gh --version dans un terminal, ou demandez à votre agent de l’installer et de s’authentifier (gh auth login).

À chaque fois qu’une étape peut être déléguée, vous trouverez un encart 🤖 avec la bonne formulation à copier-coller. Les instructions manuelles restent valables — utilisez la méthode qui vous parle le plus.

Quand utiliser GitHub Pages ?

GitHub Pages est parfait pour :

Une page de présentation pour votre projet ou votre entreprise
Un portfolio personnel
La documentation d’un logiciel
Un prototype à montrer rapidement
Un blog statique
Une petite application web (calculatrice, todo-list, jeu…)

En revanche, GitHub Pages ne sait faire qu’une chose : servir des fichiers qui ne changent pas tout seuls. On appelle ça un site statique. C’est parfait pour tout ce qui précède, mais ce n’est pas adapté si votre application a besoin de :

Stocker des données saisies par les utilisateurs (formulaires, comptes, commentaires…)
Faire tourner du code côté serveur (paiements, envois d’emails, calculs lourds…)
Cacher des clés d’API secrètes

Pas de panique

Si votre projet a besoin de ces fonctionnalités, d’autres services gratuits existent : Vercel, Netlify, Cloudflare Pages. On les mentionnera en fin de chapitre. Mais commencez par GitHub Pages : c’est le plus simple.

Première fois : un site ultra-simple en 3 minutes

Commençons par le cas le plus basique : vous avez un fichier index.html dans votre dépôt, et vous voulez le mettre en ligne.

Étape 1 : sur GitHub, allez dans votre dépôt.

Étape 2 : cliquez sur Settings (dans la barre du haut du dépôt, tout à droite).

Étape 3 : dans le menu de gauche, cliquez sur Pages.

Étape 4 : sous « Source », choisissez Deploy from a branch. Sous « Branch », choisissez main et le dossier / (root). Cliquez sur Save.

Étape 5 : attendez 30 secondes à 2 minutes. Rechargez la page. Vous verrez apparaître un encadré vert :

✅ Your site is live at https://votre-pseudo.github.io/votre-projet/

Cliquez sur le lien. Votre site est en ligne. C’est tout.

🤖 Déléguer à l’agent

Plutôt que de naviguer dans les Settings, demandez :

« Active GitHub Pages sur ce dépôt, en mode “Deploy from a branch”, sur la branche main à la racine. »

L’agent lancera quelque chose comme :

gh api -X POST /repos/:owner/:repo/pages \
  -f "source[branch]=main" -f "source[path]=/"

Et vérifiera l’URL de votre site avec :

gh api /repos/:owner/:repo/pages --jq '.html_url'

Deuxième cas : un site qui a besoin d’être « construit »

Les frameworks modernes (React, Vue, Astro, Next.js, Svelte…) ne produisent pas directement du HTML lisible par un navigateur. Ils ont besoin d’une étape de build (construction) qui transforme votre code en fichiers statiques prêts à être servis.

Concrètement, vous tapez npm run build et un dossier apparaît (souvent dist/ ou build/ ou out/) contenant le site final.

Pour ces projets, on ne peut pas se contenter de déployer la branche main directement — GitHub ne sait pas exécuter npm run build. Il faut donc demander à GitHub Actions (le service d’automatisation qu’on a vu au chapitre précédent) de faire le build pour nous, puis de livrer le résultat à GitHub Pages.

Voici le fichier magique à déposer dans votre dépôt, dans .github/workflows/deploy.yml :

name: Déployer sur GitHub Pages

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist  # ← adaptez selon votre framework

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Quelques points à noter :

path: ./dist : c’est le dossier produit par npm run build. Vite et Astro utilisent dist, Next.js utilise out, Gatsby utilise public, etc. En cas de doute, lancez npm run build en local et regardez quel dossier apparaît.
Une fois le fichier poussé sur GitHub, retournez dans Settings → Pages et choisissez Source : GitHub Actions.

🤖 Déléguer à l’agent

Plutôt que de vous battre avec la syntaxe YAML, dites simplement :

« Ajoute un workflow GitHub Actions pour déployer ce projet sur GitHub Pages. Détecte mon framework tout seul et configure le base path en fonction du nom du dépôt. »

L’agent va :

Lire votre package.json pour identifier le framework
Créer .github/workflows/deploy.yml avec les bonnes valeurs
Ajuster vite.config.js (ou équivalent) pour le base path

Activer le mode « GitHub Actions » dans les Settings via :

gh api -X PUT /repos/:owner/:repo/pages -f build_type=workflow

Commiter, pousser, et suivre le déploiement avec gh run watch

Le piège n°1 : les chemins cassés

Voici le problème qui fait perdre le plus de temps aux débutants.

Quand votre site est en local, il est servi à la racine : http://localhost:5173/. Votre fichier index.html charge ses ressources comme ceci :

<link rel="stylesheet" href="/styles.css">
<script src="/app.js"></script>

Le navigateur cherche ces fichiers à http://localhost:5173/styles.css. Tout va bien.

Mais sur GitHub Pages, votre site n’est pas à la racine du domaine — il est dans un sous-dossier :

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

Du coup, le navigateur cherche https://votre-pseudo.github.io/styles.css (à la racine du domaine), au lieu de https://votre-pseudo.github.io/mon-projet/styles.css. Résultat : une page blanche, sans style, sans JavaScript. La console du navigateur affiche plein d’erreurs 404.

La solution : dire à votre framework que le site sera servi depuis le sous-dossier /mon-projet/. On appelle ça configurer le base path (chemin de base).

Avec Vite (React, Vue, Svelte…), dans vite.config.js :

export default defineConfig({
  base: '/mon-projet/',
})

Avec Astro, dans astro.config.mjs :

export default defineConfig({
  base: '/mon-projet',
})

Avec Next.js en mode export statique, dans next.config.js :

module.exports = {
  output: 'export',
  basePath: '/mon-projet',
  images: { unoptimized: true },
}

Remplacez mon-projet par le nom exact de votre dépôt GitHub.

Le piège n°2 : le rafraîchissement qui casse tout

Si votre site a plusieurs « pages » gérées côté navigateur (par exemple avec React Router), vous avez peut-être des URLs comme /about ou /contact. Tout marche bien tant que vous naviguez en cliquant sur des liens. Mais si vous rafraîchissez la page sur /about, vous tombez sur un 404.

Pourquoi ? Parce que GitHub Pages cherche un fichier about.html qui n’existe pas. Votre application ne gère le routage qu’une fois chargée.

La solution astucieuse : créer un fichier 404.html identique à index.html. GitHub Pages servira 404.html pour toutes les URLs inconnues, votre application démarrera normalement, et son routeur prendra le relais.

Ajoutez cette étape dans votre workflow, juste après le build :

      - run: cp ./dist/index.html ./dist/404.html

Utiliser votre propre nom de domaine

Avoir votre-pseudo.github.io/mon-projet/ comme adresse, c’est bien pour commencer. Mais pour un vrai projet, vous voudrez sans doute quelque chose comme monsuperprojet.com.

Voici comment faire :

Étape 1 : achetez le domaine chez un bureau d’enregistrement (OVH, Gandi, Cloudflare Registrar, Namecheap… comptez 10-15 € par an).

Étape 2 : dans Settings → Pages sur GitHub, dans le champ « Custom domain », tapez votre domaine (par exemple monsuperprojet.com) et cliquez sur Save.

Étape 3 : chez votre bureau d’enregistrement, configurez les enregistrements DNS. Le DNS, c’est l’annuaire d’Internet : il associe un nom de domaine à une adresse de serveur.

Si vous voulez utiliser votre domaine principal (monsuperprojet.com), ajoutez 4 enregistrements de type A pointant vers les serveurs de GitHub :

A     @    185.199.108.153
A     @    185.199.109.153
A     @    185.199.110.153
A     @    185.199.111.153

Si vous voulez utiliser un sous-domaine (www.monsuperprojet.com), ajoutez un enregistrement de type CNAME :

CNAME  www  votre-pseudo.github.io

Étape 4 : patientez. La propagation DNS peut prendre de quelques minutes à plusieurs heures. Rafraîchissez la page Settings → Pages : vous devriez voir une coche verte à côté de votre domaine.

Étape 5 : cochez la case Enforce HTTPS. GitHub va automatiquement générer un certificat SSL pour votre domaine (c’est ce qui donne le petit cadenas dans le navigateur). Ça peut prendre jusqu’à 30 minutes la première fois.

🤖 Déléguer à l’agent (partiellement)

La configuration côté GitHub peut être faite par l’agent :

« Configure monsuperprojet.com comme domaine personnalisé pour GitHub Pages sur ce dépôt, et active HTTPS. »

Commandes sous-jacentes :

gh api -X PUT /repos/:owner/:repo/pages -f cname=monsuperprojet.com
gh api -X PUT /repos/:owner/:repo/pages -F https_enforced=true

⚠️ En revanche, la configuration DNS chez votre bureau d’enregistrement reste manuelle : votre agent n’a pas accès à votre compte OVH ou Gandi. Vous devez y aller vous-même (sauf si vous utilisez Cloudflare, qui a une API et un outil en ligne de commande — mais c’est une autre histoire).

Attention : tout ce que vous déployez est public

GitHub Pages sert vos fichiers à toute personne ayant l’URL. Absolument tout le monde peut :

Lire votre code HTML, CSS, JavaScript
Télécharger vos images
Voir les URLs de vos appels API

Cela veut dire JAMAIS de secret dans votre code : pas de clé d’API, pas de mot de passe, pas de token. Même si vous les mettez dans une variable d’environnement au moment du build, elles se retrouveront dans le JavaScript final, lisible par n’importe qui.

Si votre site doit appeler une API avec une clé secrète, il faut passer par un intermédiaire qui garde la clé côté serveur. Des solutions gratuites existent (Cloudflare Workers, fonctions Vercel…), mais ça dépasse le cadre de ce chapitre.

🤖 Soyez vigilant avec les agents

Les agents n’ont pas toujours l’intuition de la sécurité. Il est arrivé qu’un agent injecte une clé d’API dans le code client pour « que ça marche ». Avant chaque déploiement, demandez explicitement :

« Vérifie qu’aucune clé d’API, aucun secret et aucune variable sensible n’apparaît dans le code qui sera déployé. Liste tous les import.meta.env.VITE_* (ou équivalent) et dis-moi si certaines ne devraient pas y être. »

Et les autres solutions alors ?

GitHub Pages est top pour commencer. Mais dans certains cas, ses grandes sœurs sont plus pratiques :

Cloudflare Pages : gratuit, plus rapide, gère les previews automatiques à chaque pull request (très pratique pour tester une modif avant de la fusionner).
Netlify : pionnier du déploiement statique, très bonne expérience développeur, plan gratuit généreux.
Vercel : idéal pour les projets Next.js (c’est la boîte qui développe Next.js), très bon pour les applications plus dynamiques.

Tous ces services se branchent sur votre dépôt GitHub en quelques clics et se déploient à chaque push, comme GitHub Pages — mais avec des fonctionnalités en plus.

Le workflow typique du vibe coder

Avec un agent qui a accès à gh, le flux complet tient en quelques phrases :

« Crée-moi une page de présentation avec Astro. »
« Crée un dépôt GitHub public et pousse le code. » → gh repo create + git push
« Ajoute le workflow de déploiement GitHub Pages, active Pages en mode GitHub Actions, et surveille le déploiement jusqu’à ce qu’il soit en ligne. » → workflow YAML + gh api pour activer + gh run watch
L’agent vous donne l’URL. Vous cliquez. C’est en ligne.

De la description initiale au site public : une dizaine de minutes, sans avoir quitté le chat avec l’agent. C’est ça, le vibe coding déployé.

Vous pouvez bien sûr suivre chaque étape à la main — c’est même une bonne idée la première fois pour comprendre ce qui se passe. Mais une fois que vous avez la mécanique en tête, déléguer est libérateur.

Que faire si ça ne marche pas ?

Mon site affiche une page 404

Vérifiez que Pages est bien activé dans Settings → Pages.
Regardez l’onglet Actions : votre workflow s’est-il exécuté sans erreur ?
Si c’est un site de projet, vérifiez que le base path est bien configuré.

La page s’affiche sans style, cassée

C’est presque toujours un problème de base path mal configuré. Ouvrez les outils développeur du navigateur (F12), onglet « Console » : vous verrez des erreurs 404 avec les URLs attendues. Comparez avec l’URL réelle de votre site.

Le déploiement échoue dans GitHub Actions

Cliquez sur le workflow en erreur dans l’onglet Actions, puis sur l’étape qui a échoué. Copiez-collez le message d’erreur à votre agent : c’est souvent un problème de configuration simple à résoudre.

Tout a l’air bon mais le nouveau contenu ne s’affiche pas

Le cache du navigateur est votre ennemi. Essayez en navigation privée, ou faites un rafraîchissement forcé (Ctrl+Shift+R sur PC, Cmd+Shift+R sur Mac).

🤖 Laissez l’agent diagnostiquer

Quand quelque chose ne marche pas, les agents savent très bien investiguer tout seuls :

« Mon déploiement GitHub Pages ne fonctionne pas. Regarde le dernier workflow, identifie l’erreur et propose un correctif. »

L’agent va typiquement :

gh run list --workflow=deploy.yml --limit 1
gh run view <run-id> --log-failed
gh api /repos/:owner/:repo/pages

Puis analyser les logs et corriger le problème (souvent un chemin de build mal configuré, un base path oublié, ou une permission manquante).

Prochain chapitre : Sécurité.