6
CI e release
Alberto Balbo edited this page 2026-11-13 12:03:09 +01:00
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

CI e release

CI e release usano Gitea Actions: i workflow sono in .gitea/workflows/ e girano su un runner act_runner con label ubuntu-latest.

I workflow

File Quando parte Cosa fa
.gitea/workflows/ci.yml a ogni push su main, a ogni pull request, a mano dalla scheda Actions nel container mcr.microsoft.com/playwright:v1.56.1-noble ripete passo per passo i controlli di npm run verify (lint, formattazione, controllo dei tipi, build, HTML, link interni, end-to-end, accessibilità, conformità, Lighthouse), poi crea lo zip e ne verifica il contenuto; report Playwright (solo in caso di errore) e Lighthouse come artifact; il controllo dei link esterni è in un job separato, con lo step non bloccante
.gitea/workflows/release.yml a ogni tag vX.Y.Z controlla che tag, package.json e CHANGELOG coincidano, esegue gli stessi controlli (npm run verify), crea lo zip (npm run package) e lo pubblica nella sezione Release con scripts/release-upload.sh e l'API di Gitea, senza action esterne di release

Le run si vedono nella scheda Actions del repository. Le action di terze parti (checkout, setup-node, upload-artifact) sono indicate con l'URL completo di github.com, quindi non dipendono dalla configurazione dell'istanza; gli artifact usano upload-artifact@v3, perché la v4 non funziona su Gitea.

Stato al 13 novembre 2026

  • Pubblicata la 1.1.0 (13 novembre 2026, rework grafico): creata dal workflow Release a partire dal tag v1.1.0 (run 279, circa 6 minuti). Ha un solo allegato, sito-studio-grasso-v1.1.0.zip (430,7 KB). Prima del tag la CI su main (run 269) era passata per intero; i job sono rimasti in coda finché il runner non è stato disponibile e la verifica è durata circa 22 minuti.
  • Pubblicata la 1.0.1 (22 ottobre 2026): creata dal workflow Release a partire dal tag v1.0.1 (run 35, circa 6 minuti con l’immagine già scaricata). Ha un solo allegato, sito-studio-grasso-v1.0.1.zip (36 file, 393,8 KB), oltre ai due «Source code» che Gitea aggiunge da solo.
  • Versione 1.0.0 (16 ottobre 2026): ha ancora i file allegati nel formato di allora, cioè zip, tar.gz, SHA256SUMS.txt e BUILD-INFO.txt; il testo delle sue note è quello di allora.
  • CI verde su Gitea: la prima esecuzione completa, il 22 ottobre 2026 su main, è passata per intero: lint, formattazione, tipi, build, HTML, link interni, end-to-end, accessibilità (51), conformità (1455 controlli), Lighthouse e pacchetto zip in circa 7 minuti, più il job dei link esterni (46 interni e 17 esterni, nessuno rotto). Il report Lighthouse è allegato all’esecuzione.
  • Runner: il runner dell’istanza (label ubuntu-latest, un lavoro alla volta) ha preso in carico i job appena è stato online; finché non lo era, i job sono rimasti in coda. La rete del runner è lenta: il primo avvio ha scaricato l’immagine Playwright (oltre 1 GB) in più di venti minuti e il clone delle action da github.com richiede alcuni minuti. Dopo, l’immagine è nella cache di Docker e le esecuzioni durano pochi minuti; se il runner la elimina con una pulizia delle immagini inutilizzate, lo scarico si ripete (i limiti di tempo dei job sono larghi per questo). Lo stato del runner si controlla in Impostazioni del repository → Actions → Runner (o Amministrazione del sito → Actions → Runner).
  • Release provata su Gitea: dal tag al passo «Pubblica la release con lo zip», che ha creato la bozza, caricato lo zip e pubblicato la release con le note del CHANGELOG. Lo script è stato provato anche su una finta API di Gitea (sostituzione dello zip, bozza rimasta a metà, cartella vuota, tag non coincidente).

Accorgimenti già presi nei workflow (DECISIONS.md, D-045):

  • continue-on-error sta sullo step del controllo dei link esterni e non sul job, perché a livello di job non è garantito dalla documentazione di Gitea Actions: un sito esterno irraggiungibile non rende rossa la CI;
  • l'upload del report Lighthouse ha include-hidden-files: true (la cartella è nascosta e dalla v3.2.0 upload-artifact esclude per impostazione predefinita i file nascosti: senza l'opzione il report non verrebbe caricato);
  • il token personale per le release si chiama RELEASE_TOKEN, perché i nomi dei segreti che iniziano con GITEA_ o GITHUB_ sono riservati.
  • setup-node senza cache: npm: il server di cache del runner non è raggiungibile dal container del job e ogni esecuzione aspettava circa cinque minuti prima di proseguire con un avviso; le dipendenze si scaricano con npm ci.

Mettere in funzione il runner

  1. Sul computer del runner installare act_runner, con Docker disponibile, e registrarlo su Gitea con il token di registrazione (Impostazioni del repository → Actions → Runner, oppure Amministrazione del sito); poi avviarlo come demone o come servizio di sistema. I passi sono nella guida di Gitea Actions.
  2. Le Actions devono essere attive sul repository (Impostazioni del repository → «Enable Repository Actions»).
  3. In Impostazioni del repository → Actions → Runner il runner deve risultare online con il label ubuntu-latest, uno dei label predefiniti di act_runner (si ottengono lasciando vuoto il campo dei label alla registrazione). Se ne usa un altro, sostituire runs-on: ubuntu-latest in ci.yml e release.yml.
  4. Il runner deve raggiungere: l'istanza Gitea (all'indirizzo con cui è configurata, quello che i workflow ricevono come github.server_url), github.com (le action), mcr.microsoft.com (immagine Playwright, di grandi dimensioni: il primo avvio è lento), Docker Hub (immagine node:24 del controllo dei link esterni), nodejs.org e registry.npmjs.org.

Appena il runner è online, i job in attesa partono.

Token

Per impostazione predefinita la release è pubblicata con il token automatico del workflow. Un token personale serve se lo step di pubblicazione fallisce con errore 403 o 404, e per far partire da sola la pubblicazione sull'hosting (deploy automatico facoltativo), perché le azioni compiute con il token automatico non avviano altri workflow:

  1. Impostazioni utente → Applicazioni → Genera nuovo token, permesso write:repository;
  2. salvarlo in Impostazioni del repository → Actions → Segreti con nome RELEASE_TOKEN: se esiste, il workflow lo usa al posto del token automatico.

Non usare nomi che iniziano con GITEA_ o GITHUB_: Gitea non li accetta per segreti e variabili.

Dominio del sito

La build usa https://www.grassoezio.it (site.config.mjs). Per costruire le release per un altro dominio senza modificare il codice: Impostazioni del repository → Actions → Variabili, variabile SITE_URL (es. https://studiograssoezio.it). CI e release la usano per build e test.

Fare una nuova release

  1. Aggiornare version in package.json (SemVer) ed eseguire npm install per allineare package-lock.json.
  2. Aggiungere in CHANGELOG.md la sezione ## [X.Y.Z] - AAAA-MM-GG (diventa il testo della release).
  3. npm run verify, commit chore(release): prepara vX.Y.Z, push su main.
  4. git tag vX.Y.Z e git push origin vX.Y.Z.

La release contiene un solo allegato: sito-studio-grasso-vX.Y.Z.zip, cioè il contenuto di dist/ alla radice dell'archivio, .htaccess compreso, senza cartelle di primo livello.

Quale file scaricare. A ogni release Gitea aggiunge da solo «Source code (ZIP)» e «Source code (TAR.GZ)»: sono il codice sorgente, non il sito. Per mettere online il sito scegliere sempre lo zip sito-studio-grasso-vX.Y.Z.zip.

Senza runner, la release si pubblica a mano (comandi in docs/DEPLOY.md, sezione 10; su Windows in Git Bash). Lo script controlla che il tag sia sul server, crea la release in bozza, carica lo zip e solo alla fine la pubblica; GITEA_URL, GITEA_REPO e GITEA_TOKEN sono variabili d'ambiente dello script, non segreti del repository:

RELEASE_VERSION=vX.Y.Z npm run package
GITEA_URL=https://gitea.encke-hake.ts.net GITEA_REPO=BalboSoft/Studio_Grasso \
GITEA_TOKEN=<token write:repository> scripts/release-upload.sh vX.Y.Z