GitHub Pages: hosting gratuito per il sito, come pubblicarlo passo passo

Che cos'è GitHub Pages

GitHub Pages è un hosting gratuito per siti statici, integrato in GitHub. I file del sito si conservano in un normale repository Git, e GitHub li distribuisce via HTTPS. Ogni nuovo git push sul branch giusto aggiorna il sito, quindi non servono FTP, pannello di hosting o caricamenti manuali.

Il servizio si chiama in vari modi: «github pages», «github pages cos'è», talvolta «hosting github». La denominazione corretta è GitHub Pages: è una funzione della piattaforma GitHub, non di Git. Git stesso non pubblica nulla, si limita a conservare la cronologia delle modifiche.

Su GitHub Pages si pubblicano soprattutto documentazione di progetti, pagine personali e portfolio, blog, landing page, progetti didattici e demo di applicazioni front-end in React, Vue o Svelte, una volta compilate.

GitHub Pages è hosting per contenuti statici

La parola chiave è statico. GitHub Pages serve al browser file già pronti: HTML, CSS, JavaScript, immagini, font, JSON. Non esegue codice sul server: PHP, Python o Node.js lato server e i database non funzionano qui. Se il sito richiede registrazione, carrello o un'area amministrativa con database, serve un hosting tradizionale o una piattaforma cloud.

JavaScript nel browser funziona normalmente. Un'applicazione a pagina singola può chiamare API esterne, i moduli possono essere inviati tramite servizi di terze parti e la ricerca nel sito può essere fatta lato client.

Che tipi di siti si possono pubblicare su GitHub Pages

Esistono tre tipi di siti su GitHub Pages, e il tipo determina l'indirizzo.

Per account può esserci un solo sito utente o organizzazione, mentre i siti di progetto sono quanti volete, uno per repository. Il nome del repository del sito personale deve coincidere esattamente con il vostro login GitHub: se il login è ivan-petrov, il repository si chiama ivan-petrov.github.io.

Per i repository pubblici Pages è disponibile nel piano gratuito. Pubblicare un sito da un repository privato richiede i piani a pagamento di GitHub; il sito pubblicato, però, è comunque visibile a tutti su internet.

Come pubblicare un sito su GitHub Pages passo dopo passo

Vediamo la strada più semplice: file HTML pronti, pubblicazione da un branch. Serve un account GitHub e Git installato.

Passo 1. Creare il repository

Su GitHub create un nuovo repository pubblico. Per il sito personale chiamatelo username.github.io, per il sito di progetto il nome è libero. Poi clonatelo e aggiungete la pagina principale:

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Ciao, GitHub Pages</h1>" > index.html

La pagina principale deve chiamarsi index.html (oppure index.md o README.md: anche questi GitHub li trasforma nella home). Le maiuscole contano: Index.html non va bene.

Passo 2. Inviare i file a GitHub

git add index.html
git commit -m "Prima pagina del sito"
git push origin main

Se è la prima volta che inviate modifiche e Git chiede login e password, usate un token di accesso personale oppure l'accesso nel browser: la password normale dell'account GitHub non è accettata per git push via HTTPS.

Passo 3. Attivare Pages nelle impostazioni

Aprite il repository su GitHub, andate in Settings e nel menu laterale scegliete Pages. Nel blocco Build and deployment, nel campo Source, selezionate Deploy from a branch. Indicate sotto il branch (di solito main) e la cartella: la radice / (root) oppure /docs. Premete Save.

La cartella /docs è comoda quando nel repository c'è il codice del progetto e il sito della documentazione sta in una cartella a parte.

Passo 4. Attendere la pubblicazione

La pubblicazione richiede da pochi secondi a qualche minuto; GitHub avvisa che la prima può durare fino a 10 minuti. Lo stato della build si vede nella scheda Actions: compare il processo pages build and deployment. Quando termina con il segno di spunta verde, in Settings → Pages compare l'indirizzo del sito.

Da quel momento è semplice: modificate i file, fate commit e git push, e il sito si aggiorna da solo.

Pubblicazione con GitHub Actions

La pubblicazione da branch va bene quando nel repository ci sono file già pronti. Se invece il sito va prima compilato, per esempio un'app con Vite, React o un generatore come Hugo, è più comoda la sorgente GitHub Actions. In Settings → Pages, nel campo Source, scegliete GitHub Actions: GitHub propone modelli di workflow pronti.

Un workflow minimo per pubblicare i file statici della cartella dist dopo la compilazione è questo:

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

Il file va salvato in .github/workflows/pages.yml. Dopo git push, Actions installa le dipendenze, compila il progetto e pubblica il contenuto di dist. Il vantaggio di questo approccio è che nel repository restano solo i sorgenti, senza file compilati che appesantiscono la cronologia dei commit.

Un inciampo frequente nei siti di progetto riguarda i percorsi. Il sito si apre all'indirizzo /nome-repository/, ma il compilatore di default fa riferimento alle risorse a partire da /. Il risultato è una pagina senza stili né script. Si risolve impostando il percorso di base: in Vite con il parametro base: '/nome-repository/', negli altri compilatori con un'opzione analoga.

Jekyll e i generatori di siti statici

Con la pubblicazione da branch, GitHub elabora i file con Jekyll, un generatore di siti statici scritto in Ruby. Quindi si possono scrivere pagine in Markdown, usare temi e modelli, e GitHub le trasforma in HTML. Per un blog o una documentazione è comodo: scrivete file .md e il tema si occupa dell'aspetto grafico.

Effetto collaterale: Jekyll ignora file e cartelle il cui nome inizia con un trattino basso, come _next o _assets. Se il sito è stato compilato con un altro strumento e quelle cartelle servono, mettete nella radice un file vuoto .nojekyll:

touch .nojekyll
git add .nojekyll
git commit -m "Disattiva Jekyll"
git push

Altri generatori, come Hugo, Astro, Eleventy, MkDocs o Docusaurus, funzionano tramite GitHub Actions: la compilazione avviene nel workflow e viene pubblicata la cartella finale. GitHub Pages non conosce questi strumenti: gli bastano i file finali.

Come collegare un dominio personale a GitHub Pages

L'indirizzo username.github.io va bene per i progetti didattici, ma per un portfolio o un progetto conviene un dominio proprio. Il collegamento va in due direzioni: presso il registrar del dominio e nelle impostazioni del repository.

Configurazione DNS

Per un sottodominio come www.example.com o blog.example.com create un record CNAME che punti a username.github.io. Per il dominio radice example.com create record A verso gli indirizzi IP di GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

L'elenco aggiornato degli indirizzi, incluso l'IPv6 per i record AAAA, è nella documentazione di GitHub: verificatelo prima di configurare. Conviene impostare sia il dominio radice sia www, così GitHub reindirizza automaticamente da un indirizzo all'altro.

Configurazione nel repository

In Settings → Pages inserite il dominio nel campo Custom domain e salvate. Se pubblicate da branch, GitHub crea nel repository un file CNAME con il nome del dominio. Con la pubblicazione tramite Actions il file CNAME non serve: il dominio resta nelle impostazioni.

GitHub consiglia di verificare il dominio nelle impostazioni dell'account (sezione Pages delle impostazioni del profilo): così nessun altro può collegare il vostro dominio al proprio repository mentre il DNS punta a GitHub. Le modifiche DNS si propagano fino a un giorno, quindi se il dominio non funziona subito, attendete.

HTTPS su GitHub Pages

Per gli indirizzi *.github.io l'HTTPS è sempre attivo. Per il vostro dominio GitHub emette da solo un certificato Let's Encrypt, quando il DNS è configurato correttamente. Dopo, in Settings → Pages compare la casella Enforce HTTPS: attivatela per reindirizzare tutte le richieste HTTP verso HTTPS.

Se la casella non è attiva, il certificato non è ancora stato emesso: controllate i record DNS e attendete. Talvolta aiuta rimuovere il dominio dal campo Custom domain e inserirlo di nuovo, così parte una nuova emissione del certificato. Verificate anche che il sito non carichi immagini o script via http://: il browser bloccherebbe queste risorse come contenuto misto.

Limiti di GitHub Pages

L'hosting è gratuito, ma ha dei limiti. Sono descritti nella documentazione GitHub, e per la maggior parte dei siti personali e didattici sono più che sufficienti.

Oltre ai limiti tecnici ci sono regole d'uso: GitHub Pages non è pensato per servizi commerciali come negozi online o SaaS, né per distribuire file di grandi dimensioni. Per portfolio, documentazione, blog e landing page di un progetto va benissimo.

Un altro limite è l'assenza di configurazione lato server. Non ci sono redirect personalizzati, intestazioni di risposta o regole in stile .htaccess. Potete soltanto inserire una pagina 404.html nella radice: GitHub la mostrerà per gli indirizzi inesistenti.

Problemi tipici e come risolverli

Errore 404 su GitHub Pages

La causa più frequente è l'assenza del file index.html nella cartella scelta come sorgente. Verificate di aver scelto il branch e la cartella giusti (/ (root) oppure /docs) e che il file si chiami proprio index.html in minuscolo. La seconda causa è che il sito non è ancora pubblicato: controllate la scheda Actions e attendete la fine della build.

Se il 404 compare sulle pagine interne di un'applicazione a pagina singola quando si ricarica la pagina, il problema sta nel routing: il server non conosce l'indirizzo /about, perché quel file non esiste. Le soluzioni alternative sono il routing con hash (/#/about) oppure una copia di index.html con il nome 404.html.

Il sito non si aggiorna

Prima verificate che le modifiche siano davvero arrivate su GitHub: eseguite git status e git log origin/main --oneline -3. Poi aprite la scheda Actions: se la build è fallita, troverete una croce rossa e un log con l'errore, per esempio una sintassi sbagliata in un file Jekyll o un errore nel workflow.

Se la build è riuscita ma nel browser vedete la versione vecchia, la colpa è della cache. GitHub Pages mantiene i file in cache per alcuni minuti, e anche il browser fa la sua cache. Aggiornate la pagina svuotando la cache (Ctrl+F5 oppure Cmd+Shift+R) o apritela in una finestra privata.

Stili e immagini non si caricano

Quasi sempre il problema sono i percorsi sbagliati. Su un sito di progetto il link /style.css punta alla radice di username.github.io, non alla cartella del repository. Usate percorsi relativi (style.css, ./img/logo.png) oppure impostate il percorso di base nel compilatore. Controllate anche le maiuscole nei nomi: i server GitHub distinguono Logo.PNG e logo.png, anche se in locale su Windows tutto funzionava.

Sono scomparse le cartelle con il trattino basso

È Jekyll: non pubblica le cartelle come _app. Aggiungete nella radice il file .nojekyll oppure passate alla pubblicazione tramite GitHub Actions.

Conclusioni

GitHub Pages è il modo più rapido per pubblicare gratis un sito statico: un repository, un file index.html, la sorgente impostata in Settings → Pages, e dopo qualche minuto il sito è online all'indirizzo username.github.io. Per i siti da compilare usate GitHub Actions, per il dominio proprio i record DNS e la casella Enforce HTTPS. Tenete presenti i limiti: solo contenuti statici, senza codice lato server, con soglie di dimensione e traffico. Lavoro con GitHub, invio delle modifiche e automazione sono trattati nella pratica nel corso su Git.