Déployer sur GitHub Pages

Publiez votre application Vue.js/Vuetify gratuitement sur GitHub Pages. En quelques minutes, votre projet sera en ligne !

Prérequis

Vous devez avoir créé une application Vuetify avant de suivre ce guide.

Étape 1 : Créer le dépôt GitHub

Deux méthodes sont possibles : via WebStorm (recommandé pour débuter) ou via le terminal.

Méthode A : Avec WebStorm (interface graphique)

💡 Pourquoi WebStorm ?

WebStorm intègre Git et GitHub directement. Pas besoin de taper des commandes, tout se fait en quelques clics !

1. Activer Git dans le projet

Si Git n'est pas encore activé dans votre projet :

1. Menu VCS → Enable Version Control Integration...
2. Sélectionnez Git dans la liste déroulante
3. Cliquez OK

Vous verrez apparaître l'onglet Git en bas de WebStorm et les fichiers changeront de couleur (rouge = non suivi).

2. Faire le premier commit

1. Menu Git → Commit... (ou Ctrl+K / Cmd+K)
2. Dans le panneau qui s'ouvre :
   • Cochez tous les fichiers à inclure (ou cliquez sur la case à cocher en haut)
   • Écrivez un message : Initial commit
3. Cliquez Commit

3. Partager sur GitHub

1. Menu Git → GitHub → Share Project on GitHub
2. Si c'est votre première fois :
   • WebStorm vous demande de vous connecter à GitHub
   • Cliquez Log In via GitHub... et autorisez l'accès

3. Dans la fenêtre "Share Project on GitHub" :
   • Repository name : le nom de votre projet (ex: hello-world)
   • Remote : laissez origin
   • Description : optionnel
4. Cliquez Share

✅ C'est fait ! WebStorm a créé le dépôt sur GitHub et poussé votre code.

---

Méthode B : Avec le terminal (ligne de commande)

1. Initialiser Git dans votre projet

Ouvrez un terminal dans le dossier de votre projet :

git init
git add .
git commit -m "Initial commit"

2. Créer le dépôt sur GitHub

1. Allez sur github.com/new
2. Repository name : le nom de votre projet (ex: hello-world)
3. Laissez Public sélectionné
4. Ne cochez pas "Add a README" (vous avez déjà du code)
5. Cliquez Create repository

3. Connecter et pousser

GitHub vous affiche les commandes. Copiez celles sous "…or push an existing repository" :

git remote add origin https://github.com/VOTRE-USERNAME/hello-world.git
git branch -M main
git push -u origin main

Étape 2 : Configurer vite.config.js

Pourquoi cette configuration ?

🌐 Comprendre les URLs GitHub Pages

Votre site sera hébergé à une adresse comme :

https://votre-username.github.io/hello-world/

Remarquez le /hello-world/ à la fin ? C'est un sous-dossier !

Le problème : Par défaut, Vite génère des chemins comme /assets/main.js. Le navigateur cherchera donc https://votre-username.github.io/assets/main.js → ❌ Erreur 404 !

La solution : Dire à Vite que l'application vit dans /hello-world/. Ainsi, les chemins deviennent /hello-world/assets/main.js → ✅ Ça marche !

Ajoutez l'option base dans le fichier vite.config.js à la racine de votre projet :

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vuetify from 'vite-plugin-vuetify'

export default defineConfig({
  base: '/hello-world/',  
  plugins: [
    vue(),
    vuetify({ autoImport: true }),
  ],
})

⚠️ Remplacez /hello-world/ par le nom exact de votre dépôt GitHub !

Le base doit correspondre exactement au nom de votre dépôt, avec / au début et à la fin.

N'oubliez pas la virgule , à la fin de la ligne base: '/hello-world/', !

💡 Analogie

C'est comme donner votre adresse postale. Si vous habitez au 12 rue de la Paix, Appartement 5, vous ne pouvez pas dire juste "Appartement 5" — le facteur ne trouvera jamais ! Il faut l'adresse complète.

Étape 3 : Créer le workflow GitHub Actions

1. Qu'est-ce que GitHub Actions ?

🤖 L'automatisation expliquée simplement

Imaginez un robot qui travaille pour vous sur GitHub. Chaque fois que vous poussez du code, ce robot :

1. Prend votre code
2. L'installe sur un ordinateur virtuel
3. Le compile (transforme votre code Vue en HTML/CSS/JS)
4. Le publie sur Internet

C'est ce qu'on appelle le CI/CD (Continuous Integration / Continuous Deployment) : l'automatisation du déploiement.

2. Comment donner des instructions au robot ?

Pour dire au robot quoi faire, on écrit une "recette" dans un fichier appelé workflow. Ce fichier utilise le format YAML (extension .yml).

📁 .github/
   📁 workflows/
      📄 deploy.yml  ← Notre recette pour le robot

Le fichier est comme une recette de cuisine :

• Ingrédients : votre code, Node.js, npm
• Ustensiles : un serveur Ubuntu virtuel
• Étapes : installer, compiler, publier
• Déclencheur : quand on pousse sur main

3. Le format YAML en 2 minutes

YAML est un format simple pour écrire de la configuration. Il est plus lisible que JSON car il utilise l'indentation (espaces) pour structurer les données.

YAML

nom: Pikachu
type: Électrique
niveau: 25
attaques:
  - Tonnerre
  - Vive-Attaque

JSON équivalent

{
  "nom": "Pikachu",
  "type": "Électrique",
  "niveau": 25,
  "attaques": [
    "Tonnerre",
    "Vive-Attaque"
  ]
}

Syntaxe YAML

Syntaxe	Signification	Exemple
clé: valeur	Paire clé-valeur	name: Mon App
- élément	Élément d'une liste	- npm install
2 espaces	Indentation = hiérarchie	Voir ci-dessous
#	Commentaire	# Ceci est ignoré

# L'indentation crée la hiérarchie
parent:
  enfant: valeur      # 2 espaces = enfant de "parent"
  liste:
    - premier         # 4 espaces = enfant de "liste"
    - deuxième

4. Structure d'un fichier GitHub Actions

Un workflow GitHub Actions contient 5 sections principales :

Section	Rôle	Exemple
name	Nom du workflow (affiché dans GitHub)	name: Déployer sur GitHub Pages
on	Quand déclencher le workflow	on: push (à chaque push)
permissions	Ce que le robot peut faire	Lire le code, écrire sur Pages
concurrency	Éviter les conflits	Un seul déploiement à la fois
jobs	Les tâches à exécuter	build, deploy

Chaque job contient :

• runs-on : Le type de serveur (ex: ubuntu-latest)
• steps : La liste des étapes à exécuter

Chaque step utilise soit :

• uses: → Une action pré-faite par GitHub (ex: actions/checkout@v4)
• run: → Une commande shell (ex: npm install)

5. Créer le fichier deploy.yml

Créer le dossier

mkdir -p .github/workflows

Créer le fichier

Créez .github/workflows/deploy.yml avec le contenu suivant :

# ╔════════════════════════════════════════════════════════════════════════════╗
# ║  NOM DU WORKFLOW                                                           ║
# ╚════════════════════════════════════════════════════════════════════════════╝
# Ce nom s'affiche dans l'onglet "Actions" de GitHub
name: Déployer sur GitHub Pages

# ╔════════════════════════════════════════════════════════════════════════════╗
# ║  DÉCLENCHEURS — Quand le workflow s'exécute ?                              ║
# ╚════════════════════════════════════════════════════════════════════════════╝
on:
  # Déclenchement automatique à chaque push sur la branche main
  push:
    branches: ['main']
  # Permet aussi de lancer le workflow manuellement depuis GitHub
  workflow_dispatch:

# ╔════════════════════════════════════════════════════════════════════════════╗
# ║  PERMISSIONS — Ce que le robot a le droit de faire                         ║
# ╚════════════════════════════════════════════════════════════════════════════╝
permissions:
  contents: read       # Lire le code source du dépôt
  pages: write         # Écrire sur GitHub Pages
  id-token: write      # S'authentifier pour le déploiement sécurisé

# ╔════════════════════════════════════════════════════════════════════════════╗
# ║  CONCURRENCE — Éviter les conflits entre déploiements                      ║
# ╚════════════════════════════════════════════════════════════════════════════╝
concurrency:
  group: 'pages'              # Tous les déploiements Pages sont dans ce groupe
  cancel-in-progress: true    # Si un nouveau push arrive, annuler l'ancien

# ╔════════════════════════════════════════════════════════════════════════════╗
# ║  JOBS — Les tâches à exécuter                                              ║
# ╚════════════════════════════════════════════════════════════════════════════╝
jobs:

  # ┌──────────────────────────────────────────────────────────────────────────┐
  # │  JOB 1 : build — Compiler l'application Vue                              │
  # └──────────────────────────────────────────────────────────────────────────┘
  build:
    runs-on: ubuntu-latest    # Exécuter sur un serveur Ubuntu (gratuit)
    steps:
      # Étape 1 : Télécharger le code source depuis GitHub
      - uses: actions/checkout@v4

      # Étape 2 : Installer Node.js sur le serveur
      - uses: actions/setup-node@v4
        with:
          node-version: 20    # Version de Node.js
          cache: 'npm'        # Mettre en cache node_modules (plus rapide)

      # Étape 3 : Installer les dépendances (package.json)
      - run: npm ci

      # Étape 4 : Compiler l'application Vue → HTML/CSS/JS
      - run: npm run build

      # Étape 5 : Préparer les fichiers pour GitHub Pages
      - uses: actions/configure-pages@v4

      # Étape 6 : Empaqueter le dossier dist/ pour le déploiement
      - uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'       # Le dossier contenant le site compilé

  # ┌──────────────────────────────────────────────────────────────────────────┐
  # │  JOB 2 : deploy — Publier le site sur Internet                           │
  # └──────────────────────────────────────────────────────────────────────────┘
  deploy:
    environment:
      name: github-pages      # Environnement GitHub Pages
      url: ${{ steps.deployment.outputs.page_url }}  # URL du site déployé
    runs-on: ubuntu-latest    # Serveur Ubuntu pour le déploiement
    needs: build              # ⚠️ Attend que le job "build" soit terminé !
    steps:
      # Étape unique : Déployer les fichiers sur GitHub Pages
      - uses: actions/deploy-pages@v4
        id: deployment        # Identifiant pour récupérer l'URL

Étape 4 : Activer GitHub Pages

1. Sur GitHub, allez dans Settings de votre dépôt
2. Menu gauche → Pages
3. Build and deployment → Source : GitHub Actions

Étape 5 : Déployer !

Commitez et pushez vos modifications avec WebStorm ou en ligne de commande.

Suivez le déploiement dans l'onglet Actions de votre dépôt.

Cliquez sur le workflow pour voir les détails de l'exécution :

Une fois terminé (✅), cliquez sur le lien affiché sous le job deploy pour accéder à votre site :

https://VOTRE-USERNAME.github.io/hello-world/

Workflow quotidien

À partir de maintenant, chaque git push publie automatiquement votre site !

C'est ça le DevOps !

Code → Commit → Push → En ligne. Pas besoin de FTP ou de manipulation manuelle.

Dépannage

Le workflow ne se déclenche pas

Causes possibles et solutions :

1. GitHub Pages non activé

   • Allez dans Settings → Pages
   • Vérifiez que Source est réglé sur GitHub Actions (pas "Deploy from a branch")

2. Fichier workflow non commité

   • Le fichier .github/workflows/deploy.yml doit être commité et poussé sur GitHub
   • Vérifiez avec git status que le fichier est bien suivi

3. Branche différente de main

   • Le workflow se déclenche sur branches: ['main']
   • Si votre branche par défaut est master, changez 'main' en 'master' dans le workflow

4. Emplacement incorrect du fichier

   • Le fichier doit être à la racine : .github/workflows/deploy.yml
   • Attention : .github commence par un point (dossier caché)

5. Erreur de syntaxe YAML

   • Les espaces sont importants en YAML (2 espaces pour l'indentation)
   • Pas de tabulations ! Uniquement des espaces
   • Vérifiez la syntaxe sur YAML Lint

💡 Astuce : Déclencher manuellement

Grâce à workflow_dispatch, vous pouvez lancer le workflow manuellement :

1. Onglet Actions sur GitHub
2. Cliquez sur le workflow Déployer sur GitHub Pages
3. Bouton Run workflow → Run workflow

Page blanche

Cause : base mal configuré.

Solution : Vérifiez dans vite.config.js que base = /nom-exact-du-repo/

Erreur 404 sur les pages (Vue Router)

Cause : GitHub Pages ne gère pas le routage SPA.

Solution : Créez public/404.html :

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script>sessionStorage.redirect = location.href;</script>
  <meta http-equiv="refresh" content="0;URL='/'">
</head>
</html>

Et ajoutez dans index.html avant </head> :

<script>
  (function(){
    var r = sessionStorage.redirect;
    delete sessionStorage.redirect;
    if (r && r != location.href) history.replaceState(null, null, r);
  })();
</script>

Images qui ne s'affichent pas

Solution : Utilisez des imports :

<script setup>
import logo from '@/assets/logo.png'
</script>

<template>
  <img :src="logo" alt="Logo">
</template>

Ressources

• Vite - Static Deploy
• GitHub Pages