Déployer une application Angular sur GitHub Pages

1. Objectifs

   • Publier gratuitement une application Angular à l'adresse https://<utilisateur>.github.io/<dépôt>/
   • Installer angular-cli-ghpages et déployer en une commande avec ng deploy
   • Choisir la bonne valeur de --base-href et activer GitHub Pages sur le dépôt
   • Comprendre comment le fichier 404.html permet d'actualiser une page comme /cours/2, et connaître l'alternative withHashLocation()
   • Utiliser un nom de domaine personnalisé (--cname)
   • Automatiser le déploiement à chaque git push avec GitHub Actions

1. Présentation

   • GitHub Pages héberge gratuitement des sites statiques directement depuis un dépôt GitHub. Une application Angular compilée n'est faite que de fichiers statiques : elle peut donc y être publiée, sans serveur à louer ni à administrer.
   • Un dépôt nommé premiers-pas-angular appartenant à l'utilisateur riadh-hajji est publié à l'adresse https://riadh-hajji.github.io/premiers-pas-angular/: l'application vit dans un sous-dossier, ce qui impose --base-href.
   • GitHub Pages ne se configure pas comme Apache ou Nginx : pas de .htaccess, pas de try_files. Pour les adresses du routeur, on utilise une astuce : une copie d'index.html nommée 404.html.
   • GitHub Pages ne fait tourner aucun code côté serveur : une API PHP ou Node.js doit être hébergée ailleurs.

• Pour suivre cette leçon, il vous faut un compte GitHub, Git installé, et le projet premiers-pas-angular du chapitre. Les commandes ont été exécutées avec Angular 22.2 et angular-cli-ghpages 3.1, et le résultat a été testé dans un navigateur.

1. Envoyer le projet sur GitHub

   • Sur GitHub, créez un dépôt public nommé premiers-pas-angular, sans fichier README (le projet en a déjà un). Avec un compte gratuit, GitHub Pages n'est disponible que pour les dépôts publics.
   • Dans le dossier du projet, reliez-le au dépôt et envoyez le code (Angular CLI a déjà initialisé Git lors du ng new) :

git add .
git commit -m "Application prête à déployer"
git branch -M main
git remote add origin https://github.com/riadh-hajji/premiers-pas-angular.git
git push -u origin main

• Remplacez riadh-hajji par votre nom d'utilisateur GitHub dans toute la leçon.

1. Installer angular-cli-ghpages

   • Le paquet angular-cli-ghpages ajoute une commande ng deploy qui compile le projet puis publie le résultat sur GitHub Pages :

ng add angular-cli-ghpages

    🚀 angular-cli-ghpages is ready!

    Next steps:
      1. Read the docs: https://github.com/angular-schule/angular-cli-ghpages
      2. Deploy via: ng deploy
      3. Have a nice day!
UPDATE angular.json (2250 bytes)

• La commande installe le paquet et ajoute une cible deploy dans angular.json:

"deploy": {
  "builder": "angular-cli-ghpages:deploy"
}

1. Déployer avec ng deploy

   • L'application sera servie sous /premiers-pas-angular/: c'est la valeur à donner à --base-href, avec les deux barres obliques. Elle doit correspondre exactement au nom du dépôt, majuscules comprises.

ng deploy --base-href=/premiers-pas-angular/

404.html file created
🚀 Uploading via git, please wait...
Cleaning
Fetching origin
Checking out origin/gh-pages
Removing files
Creating .nojekyll
Copying files
Adding all
Committing
Pushing
🌟 Successfully published via angular-cli-ghpages! Have a nice day!

• En une commande, ng deploy a :
  • compilé en production avec <base href="/premiers-pas-angular/">;
  • copié index.html en 404.html;
  • créé un fichier vide .nojekyll, qui empêche GitHub de traiter le site avec Jekyll (son générateur de sites) ;
  • poussé le contenu de dist/premiers-pas-angular/browser/ dans une branche à part, gh-pages. La branche main garde votre code source, sans aucun fichier compilé.
• Contenu de la branche gh-pages après le déploiement :

.nojekyll
404.html
favicon.ico
index.html
main-7W7XMOG5.js
styles-5INURTSO.css

• Pour ne pas retaper l'option à chaque fois, ajoutez-la dans angular.json. ng deploy suffit alors :

"deploy": {
  "builder": "angular-cli-ghpages:deploy",
  "options": {
    "baseHref": "/premiers-pas-angular/"
  }
}

1. Activer GitHub Pages

   • Au premier déploiement, indiquez à GitHub quelle branche publier. Dans le dépôt : Settings → Pages → rubrique Build and deployment → Source: Deploy from a branch, puis branche gh-pages et dossier / (root) → Save.
   • Après une à deux minutes, la page Settings → Pages affiche l'adresse du site : https://riadh-hajji.github.io/premiers-pas-angular/. L'onglet Actions du dépôt montre la publication en cours (pages build and deployment).
   • Les déploiements suivants sont publiés automatiquement : il suffit de relancer ng deploy.

1. Actualiser une page : le rôle de 404.html

   • Comme sur tout serveur, actualiser /premiers-pas-angular/cours/2 demande à GitHub un fichier qui n'existe pas. GitHub répond alors avec le fichier 404.html du site, s'il y en a un.
   • Ce 404.html étant une copie d'index.html, Angular démarre, lit l'adresse /cours/2 et affiche la page « Angular ». Vérifié sur une copie du site servie de la même façon : sans 404.html, le navigateur affiche « 404 Not Found » ; avec, la page du cours s'affiche.
   • Le serveur répond tout de même avec le code 404: la console affiche Failed to load resource: the server responded with a status of 404, sans conséquence pour l'utilisateur, mais les moteurs de recherche n'indexeront pas ces pages.

• L'autre solution consiste à placer l'adresse du routeur après un #: /premiers-pas-angular/#/cours/2. Le navigateur n'envoie jamais au serveur ce qui suit le #; le serveur ne voit que /premiers-pas-angular/ et répond index.html avec un code 200. Il suffit d'ajouter withHashLocation():

import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
import { provideRouter, withComponentInputBinding, withHashLocation } from '@angular/router';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideBrowserGlobalErrorListeners(),
    provideRouter(routes, withComponentInputBinding(), withHashLocation())
  ]
};

• Vérifié sur un serveur sans 404.html: /hash/#/cours/2 s'affiche directement. Les liens routerLink n'ont pas à être modifiés, Angular ajoute le # lui-même. En contrepartie, les adresses sont moins lisibles : gardez la solution 404.html par défaut.

1. Les options de ng deploy

• --dry-run permet de contrôler les options avant de publier :

ng deploy --base-href=/premiers-pas-angular/ --cname=cours.mon-site.tn --dry-run

Dry-run: No changes are applied at all.
Dry-run / SKIPPED: cleaning of the cache directory
Dry-run / SKIPPED: copying of index.html to 404.html
Dry-run / SKIPPED: publishing folder 'dist/premiers-pas-angular/browser' with the following options: {
  "cname": "a CNAME file with the content 'cours.mon-site.tn' will be created",
  …

1. Utiliser un nom de domaine personnalisé

   • Pour publier l'application sur https://cours.mon-site.tn au lieu de github.io:
     • chez le fournisseur du domaine, créez un enregistrement DNS de type CNAME: cours → riadh-hajji.github.io;
     • déployez avec --cname. L'application est alors à la racine du domaine : --base-href redevient /;
     • dans Settings → Pages, vérifiez le domaine et cochez Enforce HTTPS quand la case devient disponible.

ng deploy --base-href=/ --cname=cours.mon-site.tn

• Utilisez toujours l'option --cname plutôt que de saisir le domaine seulement dans les réglages : chaque ng deploy remplace le contenu de gh-pages, et un fichier CNAME absent ferait perdre le domaine.

1. Automatiser avec GitHub Actions

   • Plutôt que de déployer depuis votre machine, GitHub peut compiler et publier l'application à chaque git push sur main. Créez le fichier .github/workflows/deploiement.yml:

name: Déploiement sur GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:        # bouton « Run workflow » dans l'onglet Actions

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

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  compiler:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx ng build --base-href=/premiers-pas-angular/
      - run: cp dist/premiers-pas-angular/browser/index.html dist/premiers-pas-angular/browser/404.html
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist/premiers-pas-angular/browser

  publier:
    needs: compiler
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploiement.outputs.page_url }}
    steps:
      - id: deploiement
        uses: actions/deploy-pages@v5

• Dans Settings → Pages, choisissez alors Source: GitHub Actions (au lieu de Deploy from a branch). La branche gh-pages n'est plus utilisée.
• À chaque git push, l'onglet Actions montre les deux étapes ; une coche verte signale que le site est à jour.
• Les permissions pages: write et id-token: write sont indispensables : sans elles, l'étape deploy-pages échoue.
• Les numéros de version (@v7, @v5) sont ceux en vigueur lors de la rédaction : vérifiez-les sur la page de chaque action.

1. Activité 1 : un premier déploiement

   • Créer le dépôt public premiers-pas-angular, y pousser le projet, installer angular-cli-ghpages et lancer ng deploy --base-href=/premiers-pas-angular/.
   • Activer GitHub Pages sur la branche gh-pages et ouvrir l'adresse indiquée.

• Vérifier : l'application s'affiche ; la branche gh-pages contient index.html, 404.html et .nojekyll.
• Pourquoi le code TypeScript n'apparaît-il pas dans la branche gh-pages?

1. Activité 2 : la bonne adresse de base

   • Redéployer avec --base-href=/, puis ouvrir le site et la console (F12).
   • Redéployer avec la bonne valeur.

• Vérifier : avec /, la page reste blanche et main-….js est en 404 ; avec /premiers-pas-angular/, tout fonctionne.
• Quelle adresse le navigateur a-t-il demandée pour main-….js dans le premier cas ?

1. Activité 3 : actualiser une page

   • Ouvrir /premiers-pas-angular/cours/2 dans un nouvel onglet et observer l'onglet Réseau des outils de développement.
   • Supprimer 404.html directement dans la branche gh-pages sur GitHub, attendre la publication, et recommencer.

• Vérifier : avec 404.html, la page du cours s'affiche malgré un code 404 ; sans, GitHub affiche sa page d'erreur.
• Comment rétablir le fichier en une commande ?

1. Activité 4 : le routage par #

   • Ajouter withHashLocation() au routeur, redéployer, et naviguer dans l'application.
   • Actualiser une page de cours, puis recopier son adresse dans un autre navigateur.

• Vérifier : les adresses contiennent #/cours/2; l'actualisation fonctionne et l'onglet Réseau montre un code 200.
• Citez un avantage et un inconvénient de cette solution par rapport à 404.html.

1. Activité 5 : un déploiement automatique

   • Ajouter le fichier .github/workflows/deploiement.yml, choisir la source GitHub Actions dans les réglages de Pages, puis modifier un texte et faire git push.
   • Suivre l'exécution dans l'onglet Actions.

• Vérifier : les étapes compiler et publier réussissent, et la modification est en ligne sans avoir lancé ng deploy.
• Retirez la ligne pages: write: quelle étape échoue, et pourquoi ?

1. Erreurs fréquentes

1. À retenir

   • GitHub Pages publie gratuitement des fichiers statiques à l'adresse https://<utilisateur>.github.io/<dépôt>/.
   • ng add angular-cli-ghpages, puis ng deploy --base-href=/<dépôt>/: compilation, 404.html, .nojekyll et publication dans la branche gh-pages.
   • À activer une fois : Settings → Pages → Deploy from a branch → gh-pages.
   • 404.html (copie d'index.html) permet d'actualiser les pages du routeur ; withHashLocation() est l'alternative sans code 404.
   • Domaine personnalisé : enregistrement DNS CNAME, --cname et --base-href=/.
   • GitHub Actions déploie automatiquement à chaque git push sur main.

Sur GitHub Pages, on ne règle pas le serveur : on lui donne les bons fichiers. Une adresse de base exacte et un 404.html suffisent à faire fonctionner tout le routeur.