Workflow di release e CI

Una mappa a colpo d'occhio di ogni workflow di GitHub Actions nei repo di Playroll — cosa lo attiva e cosa fa — più quale skill guida quale workflow. Usala per rispondere a "cosa succede davvero quando faccio push di questo tag?" senza leggere lo YAML.

Come scorre una release (la versione breve)

1. cpp viene taggato vX.Y.Z → la sua CI compila il core e carica uno zip su S3 (nessun impatto sugli utenti ancora).
2. installer viene taggato playroll/<track>/vX.Y.Z (agganciato a tag cpp/ui specifici tramite release-manifest.yml) → la sua CI compila + firma l'installer, pubblica sul CDN e scrive una riga in Supabase app_releases_v2.
3. Un rollout (rollout.yml / un override) decide chi lo riceve. Pubblicazione e audience sono passi distinti — una release pubblicata non raggiunge nessuno finché un rollout o un override non lo prende di mira.

L'artifact rivolto all'utente è il file firmato Playroll_Setup_X.Y.Z.exe, non lo zip del core cpp. La UI non viene mai rilasciata da sola — è agganciata e compilata dall'installer.

Workflow per repo

Repo	Workflow	Trigger	Cosa fa
playroll-cpp	build-check.yml	push/PR su main,develop,ci/**	Compila il core in Release come verifica. Nessuna pubblicazione.
playroll-cpp	build-release.yml	tag v*, o dispatch manuale	Compila il core e carica playroll-core-build.zip su S3. Se l'artifact esiste già per quel tag, salta la build (claim check). Non effettua il rollout agli utenti.
playroll-cpp	lambda-deploy.yml	push su main che tocca lambda_src/**, o dispatch	Effettua il deploy delle funzioni AWS Lambda.
playroll-installer	build-check.yml	PR su main	Compila l'installer completo (nessuna firma, nessuna pubblicazione) come verifica. Fa checkout di cpp/ui su main.
playroll-installer	dry-run.yml	dispatch manuale	Prova di sola build dell'installer; non pubblica nulla.
playroll-installer	release.yml	tag playroll/{stable,test,dev}/v*	Compila + firma + pubblica l'installer, scrive app_releases_v2. Solo sul track test, effettua automaticamente un rollout forzato al 100% all'intera coorte di tester dello staff. dev/stable non effettuano rollout automatico.
playroll-installer	rollout.yml	dispatch manuale	Decide chi riceve una release pubblicata — scrive app_rollouts_v2 / override.
playroll-installer	promote.yml	dispatch manuale	Ripubblica una release esistente su un altro track senza ricompilare né rifirmare.
playroll-installer	hotfix-tester-smoke.yml	push/PR che tocca hotfix-tester.ps1, o dispatch	Esegue hotfix-tester.ps1 -DryRun e verifica gli invarianti del piano. Una rete di sicurezza affinché un rename o un cambio di schema rompa la CI, non il prossimo hotfix reale.
playroll-ui	build-check.yml	push/PR su main,develop,ci/**	Lint + typecheck + test + build. La UI viene distribuita solo come parte di una release dell'installer.

Skill e gli script/workflow che guidano

Il flusso di release canonico, guidato dalla CI, vive nelle skill a livello di workspace (ec-workspace/.claude/skills/), ereditate da ogni repo.

Skill / script	Vive in	Guida	Ambito
playroll-doctor	skill di workspace	nulla (sola lettura)	Verifica che l'ambiente di release sia configurato. Eseguilo prima di rilasciare.
playroll-release	skill di workspace	git-flow su cpp/ui + installer release.yml; anche la promotion	Cosa viene distribuito. Include una sezione "Hotfix mirato a tester specifici".
playroll-rollout	skill di workspace	installer rollout.yml → app_rollouts_v2	Chi lo riceve.
/hotfix-release	comando playroll-cpp	il dettaglio dell'hotfix lato cpp (branch dal tag di release, verifica che compili sulla vecchia base, pre-stage dell'artifact S3)	Delega a playroll-release / hotfix-tester.ps1 per la release dell'installer + il rollout.
hotfix-tester.ps1	script playroll-installer	release sul track dev + override forzato a una lista esplicita di utenti	Hotfix deterministico per singolo/multi tester. Il track è hardcoded a dev, quindi non può mai effettuare il rollout automatico a tutti. -DryRun non scrive nulla.
release-testers.ps1, rollout-testers.ps1, local-release.ps1	script playroll-installer	publish/rollout locale	Fallback da macchina di sviluppo, non il percorso predefinito.

Trabocchetti da conoscere

• Il track test si propaga a tutti. Taggare playroll/test/v* effettua automaticamente il rollout della build a tutti i tester dello staff (cablato in release.yml). Per puntare a uno o pochi tester, usa il track dev + un override — hotfix-tester.ps1 fa esattamente questo e rimuove la scelta (nessun parametro -Track).
• Il tag cpp non è un rollout. Mette solo in stage l'artifact del core su S3. Nessuno riceve nulla finché non c'è la release dell'installer + un rollout.
• Pubblicazione ≠ audience. release.yml/playroll-release pubblicano; rollout.yml/playroll-rollout scelgono chi lo riceve. Tienili separati.