arboretum/docs/CI_RUNNERS.md

Runners Gitea Actions · ajouter Windows (et macOS)

Ce document explique comment activer le build Windows de l'app de bureau dans la CI. Il est écrit pour être appliqué tel quel sur git.lidge.fr (Gitea 1.25).

Pourquoi un runner Windows est obligatoire

Le cross-build Windows depuis Linux ne peut pas fonctionner, pour deux raisons vérifiées dans node_modules/@homebridge/node-pty-prebuilt-multiarch :

1. scripts/check-prebuild.js sort en succès dès que le binaire de l'hôte existe, donc prebuild-install n'est jamais appelé et aucun binaire win32 n'est téléchargé (le tarball publié ne contient que prebuilds/linux-*) ;
2. scripts/post-install.js ne copie conpty.dll et OpenConsole.exe que si la plateforme de build est win32. Sans eux, pas de ConPTY, donc aucun terminal dans l'app.

Un build produit sous Wine serait donc installable mais inutilisable. C'est pour cela que packages/desktop/README.md ne propose plus cette voie.

État actuel

Plateforme	Runner	Build
Linux	ubuntu-latest (déjà en place)	automatique à chaque tag desktop-v*
Windows	à enregistrer	job windows, activé par la variable ENABLE_WINDOWS_BUILD
macOS	aucun	manuel (npm run dist:mac sur un Mac)

Le job Windows est conditionné par if: vars.ENABLE_WINDOWS_BUILD == 'true'. Tant que la variable n'existe pas, le job est sauté : la release Linux part normalement. Sans cette condition, un job runs-on: windows-latest sans runner disponible resterait en attente et bloquerait la release entière.

1. Préparer la machine Windows

Prérequis (Windows 10 1809+ ou Windows 11, x64) :

• Git pour Windows (fournit aussi bash, utilisé par les étapes shell: bash du workflow) ;
• Node.js 22.21.1 (même version que NODE_VERSION dans le workflow) ;
• rien d'autre : node-pty s'installe via des binaires précompilés, aucun compilateur C++ n'est requis.

Vérification rapide dans PowerShell :

node --version   # v22.21.1
git --version
bash --version   # fourni par Git for Windows

2. Enregistrer le runner

Récupérer un jeton d'enregistrement dans Gitea : Site Administration → Actions → Runners → Create new runner (jeton d'instance), ou au niveau du dépôt : Settings → Actions → Runners.

Puis, dans PowerShell (répertoire dédié, par exemple C:\actions-runner) :

mkdir C:\actions-runner; cd C:\actions-runner
# Binaire act_runner pour Windows (adapter la version à celle de votre Gitea)
Invoke-WebRequest -Uri "https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-windows-amd64.exe" -OutFile act_runner.exe

.\act_runner.exe register --no-interactive `
  --instance https://git.lidge.fr `
  --token <JETON_DENREGISTREMENT> `
  --name windows-builder `
  --labels windows-latest:host

Le label windows-latest:host est essentiel : :host signifie « exécuter directement sur la machine », sans conteneur (il n'y a pas d'image Docker Windows utilisable ici), et windows-latest est le nom attendu par runs-on dans le workflow.

Démarrage manuel pour un premier essai :

.\act_runner.exe daemon

3. Exécuter le runner en service

Pour qu'il survive aux redémarrages, créer une tâche planifiée « à l'ouverture de session » (même principe que arboretum install sur Windows) :

schtasks /Create /TN "GiteaActRunner" /TR "C:\actions-runner\act_runner.exe daemon" `
  /SC ONLOGON /RL LIMITED /F
schtasks /Run /TN "GiteaActRunner"

Alternative : NSSM pour un vrai service Windows, si le runner doit tourner sans session ouverte. Attention : un service hors session n'a pas accès au profil utilisateur.

4. Activer le job dans la CI

Dans Gitea, sur le dépôt johanleroy/arboretum : Settings → Actions → Variables → Add Variable

Nom	Valeur
ENABLE_WINDOWS_BUILD	true

5. Vérifier sans créer de tag

Le workflow accepte workflow_dispatch : Actions → Desktop Release → Run workflow. Dans ce mode, le garde-fou « tag == version » est ignoré et rien n'est attaché à une release ; les installeurs sont récupérables dans les artefacts du run (desktop-windows).

Contrôles à faire sur l'installeur produit :

1. l'installeur NSIS s'exécute et propose le répertoire d'installation ;
2. l'app démarre et affiche l'IDE sans écran de connexion (le token passe par le descripteur 3 ; c'est le point le plus susceptible de différer sur Windows, cf. packages/desktop/src/main/daemon.ts) ;
3. un terminal s'ouvre et répond (ConPTY présent) ;
4. le CLI claude est trouvé (sinon renseigner son chemin dans Réglages → Claude CLI) ;
5. « Démarrer le projet » lance bien les commandes sous PowerShell.

6. Signature de code

Aucun binaire n'est signé. SmartScreen affichera « éditeur inconnu » au premier lancement : choisir « Informations complémentaires » puis « Exécuter quand même ». Pour signer plus tard, ajouter les secrets CSC_LINK (certificat .pfx encodé en base64) et CSC_KEY_PASSWORD au dépôt : electron-builder les utilise automatiquement, sans changement de workflow.

Repli si aucun runner n'est possible

Sur une machine Windows, avec le dépôt cloné :

npm ci
cd packages\desktop
npm ci
npm run dist:win

Puis attacher packages\desktop\release\*.exe, latest.yml et les .blockmap à la release desktop-vX.Y.Z depuis l'interface Gitea. Le canal d'auto-update (desktop-latest) doit recevoir les mêmes fichiers, sinon les utilisateurs Windows ne verront pas la mise à jour.