I progetti che ci troviamo a sviluppare sono spesso accompagnati da una documentazione più o meno strutturata, che può essere il singolo file di markdown, piuttosto che il classico sito web statico. E' importante, però, dare visibilità di questa documentazione a chi visita il repository e, pertanto, può essere comodo esportare tutto su un App Service di Azure o, piuttosto, su un Blob Storage. In GitHub, però, abbiamo a disposizione le GitHub Pages, un sistema di hosting per i siti web generati dai repository.

Funzionano in due modalità. Con la prima, si può agganciare il website direttamente ad un branch e una folder specifica a partire dalla root del repository: questo è particolarmente utile nei casi in cui la documentazione è sempre disponibile e aggiornata (manualmente o automaticamente) e salvata nel repository. Tuttavia, questo approccio non è sempre praticabile. Infatti, in scenari specifici, non ci interessa avere nel repository tutto il codice che può essere autogenerato, pertanto è altrettanto fattibile, anche se al momento della scrittura di questo articolo in fase beta, pubblicare dei contenuti generati da un workflow di GitHub.

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3

    - name: Build storybook
      shell: bash
      run: yarn run build:storybook

    - name: Prepare static site
      uses: actions/upload-pages-artifact@v1
      with:
        path: ./storybook-static

Nell'esempio abbiamo sfruttato il classico scenario di un'applicazione React con Yarn/npm, dove andiamo a generare lo storybook, ovvero una sorta di documentazione dei componenti che andranno a comporre la UI. Sebbene questo è contenuto statico, non ha senso che ci riportiamo le informazioni anche sul repository. Una volta generate, possono essere pubblicate direttamente nelle GitHub Pages.

A prescindere dal comando per compilare/generare la documentazione, che chiaramente dipende da ciascuna applicazione, per pubblicare un contenuto tramite GitHub Actions in GitHub Pages, abbiamo la necessità di caricare un artifact, chiamato di default github-pages, che include il sito web statico.

deploy:
  name: Publish storybook
  runs-on: ubuntu-latest
  needs: [ build ]
  environment:
    name: storybook
    url: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
  steps:
  - name: Deploy to GitHub Pages
    uses: actions/deploy-pages@v1

Il secondo passaggio è dato dalla action di deploy-pages, che andrà semplicemente a prendere l'artifact caricato nel job precedente e lo caricherà, rendendo il sito web visibile. L'indirizzo di pubblicazione è, di default, https://.github.io/, ma può essere personalizzato con un nome DNS.

Il vantaggio dell'usare le GitHub Pages al posto di Azure, in questo caso specifico, risiede nella facilità con cui possiamo gestire i permessi e la visibilità del sito web stesso. Di fatto, quando il repository pubblico, anche le GitHub Pages saranno pubbliche e accessibili a chiunque, mentre se il repository è privato, allora sarà visibile le GitHub Pages saranno visibili solo a chi ha accesso al repository stesso. In Azure, seppur non è molto più complesso, va tutto configurato a mano e incorriamo in costi aggiuntivi.