Deploy sito web Hugo in repository privato con GitHub Pages (2025)

Introduzione

#

Hugo è un potente generatore di siti web statici che sto approfondendo in questi giorni. La sua semplicità e l’immediatezza con cui mi permette di creare e condividere contenuti mi hanno spinto ad aprire il blog che stai leggendo.

In questo articolo voglio condividere un esperimento nato dalla pura curiosità: capire se fosse possibile mantenere privato il repository GitHub con il codice sorgente del mio sito e allo stesso tempo pubblicarlo tramite GitHub Pages, un servizio che normalmente richiede un account Pro per il deploy da repository privati.

Non si tratta di una necessità reale per questo progetto personale, ma piuttosto del desiderio di trovare una soluzione alternativa usando gli strumenti a disposizione. Dopo aver consultato alcuni articoli un po’ datati e/o incompleti, sono arrivato alla configurazione che vi mostrerò passo-passo di seguito.

Creazione sito

#

Iniziamo creando un sito di prova con Hugo installando un tema tramite i sottomoduli di Git. Se hai già tutto pronto puoi passare alla prossima sezione:

1. Crea la directory con il sito web:

   hugo new site miosito-sorgente
   

2. Spostati nella directory appena creata e inizializza il repository (locale):

   cd miosito-sorgente
   git init
   

3. Crea il sito web con Hugo e aggiungi un tema:

   hugo
   git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
   

4. Rimuovi la configurazione standard di Hugo e sostituiscila con quella fornita dal tema:

   rm hugo.toml
   mkdir -p config/_default/; cp themes/blowfish/config/_default/* config/_default/
   

5. Decommenta la linea # theme = "blowfish" # UNCOMMENT THIS LINE nel file config/_default/hugo.toml
6. Avvia il server e verifica che tutto funzioni correttamente:

   hugo server
   

Se tutto è configurato correttamente dovresti vedere una pagina simile alla seguente:

Setup repository

#

Ora è necessario creare due repository su GitHub:

• Repository privato (miosito-sorgente) in cui salveremo il codice sorgente del sito per mantenerlo privato

  

• Repository pubblico (miosito): qui pubblicheremo il codice del sito generato tramite Hugo che verrà pubblicato tramite GitHub Pages

  

Dalla directory locale del sito, esegui il push del codice verso il repository privato:

git remote add origin https://github.com/<username>/miosito-sorgente.git
git branch -M main
git add .
git commit -m "first commit"
git push -u origin main

Creazione Personal Access Token

#

Dopo aver caricato il codice sorgente su GitHub è necessario creare un Personal Access Token (PAT) per concedere al repository privato l’accesso al repository pubblico.

Definisci un nome per il PAT e restringi l’accesso al solo repository pubblico (miosito) creato precedentemente.

Prima di confermare la creazione ricordati di assegnare i permessi corretti al token per poter gestire correttamente il deploy verso il repository pubblico:

Conferma la creazione, copia il token generato e salvalo in un posto sicuro come ad esempio un password manager.

Imposta il PAT come segreto nel repository privato

#

Dopo aver creato il PAT devi aggiungerlo ai segreti del repository privato per poterlo utilizzare in maniera sicura in fase deploy.

Dalle impostazioni del repository privato è possibile aggiungere il token come segreto svolgendo i seguenti passi:

Aggiungi un nuovo segreto al repository sotto il nome di BLOG_PAT_DEPLOY e incolla il valore del token copiato precedentemente:

GitHub Action

#

Per creare il seguente workflow mi sono basato sulla guida all’hosting e deploy del tema Hugo che sto utilizzando (Blowfish) e altre guide come quella di Finisky Garden. Nessuna di queste purtroppo copriva tutti i problemi che ho riscontrato durante il deploy, così ho pensato potesse tornare utile a qualcuno condividere il mio workflow:

• Checkout: controlla il codice sorgente
• Setup Hugo: prepara l’ambiente Hugo per i passi successivi
• Build: crea il sito statico da pubblicare
• Deploy: utilizza l’azione di deploy di GitHub Pages per pubblicare il sito web

Crea il file YAML .github/workflows/gh-pages.yml nella directory del sito con il seguente contenuto:

name: GitHub Pages

on:
  push:
    branches:
      - main

permissions:
    contents: write

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.BLOG_PAT_DEPLOY }}
          external_repository: the-wits/miosito
          publish_branch: gh-pages
          publish_dir: ./public
          single-commit: true
          commit-message: "Deploy da sorgente"

Modifica i seguenti campi del workflow:

1. branches: - <nome_branch>: imposta il nome del branch nel repository privato che innesca l’esecuzione del workflow
2. personal_token: ${{ secrets.<NOME_PAT> }}: imposta il nome del segreto creato precedentemente
3. external_repository: <tuo-username>/<nome-repo-pubblico>: imposta il tuo username e il nome del repository pubblico in cui verrà pubblicato il sito

Pubblicazione

#

Aggiungi il workflow al repository privato e abilita GitHub Pages nel repository pubblico. Dalle impostazioni abilita GitHub Pages per pubblicare il tuo sito web dal branch gh-pages:

Se tutto è configurato correttamente, si innescherà il workflow definito in gh-pages.yaml che compilerà il sito con Hugo e pubblicherà solo l’output statico nel repository pubblico:

Questo problema è causato dall’assenza del parametro baseURL nella configurazione del sito: aggiungere la riga baseURL = "https://the-wits.github.io/" al file di configurazione config/_default/hugo.toml come segue:

# config/_default/hugo.toml

# -- Site Configuration --
# Refer to the theme docs for more details about each of these parameters.
# https://blowfish.page/docs/getting-started/

theme = "blowfish" # UNCOMMENT THIS LINE
baseURL = "https://the-wits.github.io/miosito/"

Salva le modifiche e caricale nel repository privato. Ad ogni push sul branch main verrà invocato il workflow e qualche secondo dopo il sito sarà disponibile online:

Dominio personalizzato (Opzionale)

#

GitHub Pages permette anche di impostare un dominio personalizzato per il sito web appena pubblicato. Qualora volessi aggiungerlo, puoi farlo dalle impostazione del repository pubblico:

Dal pannello di gestione del tuo dominio dovrai creare un record DNS di tipo CNAME che punti a <tuo-username-gh>.github.io (nel mio caso the-wits.github.io). Una volta aggiunto il record DNS, GitHub verificherà automaticamente la proprietà del dominio.

Durante i miei test ho riscontrato un problema molto fastidioso: ad ogni deploy il workflow eliminava il file CNAME creato da GitHub per associare il dominio personalizzato al sito. Di conseguenza dopo ogni deploy era necessario riconfermarlo manualmente.

Per evitare a questo comportamento ho creato un file CNAME nella directory static del progetto con il nome del dominio personalizzato.

Il contenuto della directory static viene copiato automaticamente nella radice del sito generato e pubblicato nel branch gh-pages dopo il deploy. In questo modo il file CNAME viene ripristinato ad ogni deploy automatizzando completamente il rilascio dei nuovi contenuti.

Troubleshooting

#

1. Verifica che il workflow si trovi nella directory corretta (.github/workflows/):
   • .github deve presentare il punto iniziale
   • workflows deve essere plurale con la s finale
2. Verifica che il branch indicato nel workflow sia quello corretto. Ogni volta che effettuerai un push del codice nel branch indicato, verrà lanciato il workflow.
3. Dopo aver impostato un dominio personalizzato, potresti non avere subito la possibilità di forzare il protocollo HTTPS. In questo caso è normale dover attendere qualche minuto:
   • Quando aggiungi un dominio personalizzato, GitHub Pages deve richiedere un certificato SSL a una CA come Let’s Encrypt. Questo processo non non è immediato e può richiedere un po’ di tempo
   • Se il problema persiste anche dopo diversi minuti prova a reinserire nuovamente il domino e ripetere la procedura di verifica DNS