Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01X3cUrskCRGZn3VbEmyyVCS
20 KiB
Faire tourner ses jobs CI sur sa propre machine
English — la version anglaise est la référence.
Les workflows de .github/workflows/ tournent aussi sur la forge (git.jumphp.net, Forgejo Actions), avec la même syntaxe que
GitHub Actions (les actions/* viennent de github.com via le DEFAULT_ACTIONS_URL de la forge). Sur les machines de la forge
ne tournent que les jobs de son administrateur : on apporte son propre runner, sur un PC, un VPS ou une VM. Cette page dit
lequel choisir, comment l'installer avec un script, et les pièges.
| Votre projet est sur | Runners | Comment |
|---|---|---|
| GitHub | ceux de GitHub (hébergés), ou les vôtres (self-hosted) | les workflows de votre dépôt, sur les runners de votre compte (notes GitHub) |
| git.jumphp.net | vos propres runners | cette page |
1. De quel runner ai-je besoin ?
| Ce que vous construisez | Il faut | Runner (label) | Votre machine | Script |
|---|---|---|---|---|
builds JumPHP, tests du moteur, Android, web, tout ce qui est Docker |
Linux + Docker | Linux (ubuntu-latest) |
Linux / macOS / VPS | bin/jumphp runner:install --scope ... --name ... |
| idem | Linux + Docker | Linux (ubuntu-latest) |
Windows | tools/runner/install-wsl-linux-runner.ps1 (WSL2 + Docker Engine dedans) |
la bibliothèque Windows du runtime Tauri (jumphp_tauri.dll), .exe, installeurs Windows |
Windows + MSVC + Rust | Windows (windows-latest) |
Windows | tools/runner/install-windows-runner.ps1 |
| idem | Windows + MSVC + Rust | Windows (windows-latest) |
Linux | tools/runner/windows-vm/ (une VM Windows QEMU/KVM sans écran, puis le script ci-dessus dedans) |
| apps macOS / iOS | un Mac + Xcode | macOS | un Mac | pas de script (les Mac de GitHub, docs/apple.md) |
Plusieurs runners sur la même machine sont possibles (un PC Windows peut héberger le runner Windows et le runner Linux WSL2).
Récupérer les scripts sans dépôt cloné : bin/jumphp runner:scripts <dossier> copie tools/runner/, ou les télécharger du dépôt.
Le jeton d'enregistrement (tous les cas) : dans la forge, l'organisation (ou votre utilisateur) > Paramètres > Actions >
Runners > Créer un nouveau runner. Il ne sert qu'une fois et pour ce seul utilisateur / cette seule organisation. Donnez-le aux
scripts par la variable d'environnement JUMPHP_RUNNER_TOKEN (pas en argument : les lignes de commande sont visibles des autres
processus et restent dans l'historique du shell).
2. Linux, macOS ou VPS : une commande
Seul Docker est nécessaire.
bin/jumphp runner:install --scope user/<votre-login> --name mon-pc # vos dépôts
bin/jumphp runner:install --scope org/<organisation> --name vps-1 # ceux d'une organisation
- Limité à UN utilisateur ou UNE organisation, jamais à toute l'instance (les inscriptions sont ouvertes : un runner d'instance laisserait n'importe qui exécuter du code chez vous).
- Les jobs tournent dans le Docker propre au runner (
docker:dind) : ledocker.sockde l'hôte n'est jamais monté. - Le jeton :
JUMPHP_RUNNER_TOKEN, ou fabriqué par l'API avec votre jeton de forge (JUMPHP_FORGE_TOKEN, ou celui que git a déjà). Il n'est pas conservé. - Fichiers :
~/.jumphp/runners/<nom>/. Suivre :docker compose -f ... logs -f. - Retirer :
bin/jumphp runner:remove --name mon-pc, puis le supprimer dans la forge. - Sur un VPS : installer Docker, récupérer JumPHP, lancer la commande (
restart: unless-stopped).
3. Windows, runner natif (builds Windows)
tools/runner/install-windows-runner.ps1, PowerShell 5.1+, en administrateur.
Windows 10 ou 11 64 bits, ~15 Go libres, internet.
$env:JUMPHP_RUNNER_TOKEN = '<jeton d enregistrement>'
.\install-windows-runner.ps1 -Scope org/<organisation> -Name bureau-pc
(Scripts bloqués : powershell -ExecutionPolicy Bypass -File .\install-windows-runner.ps1 -Scope ....)
Paramètres : -Instance (défaut https://git.jumphp.net), -Scope org/<nom>|user/<login> (obligatoire), -Token (sinon
JUMPHP_RUNNER_TOKEN, sinon demandé en saisie masquée), -Name, -Labels (défaut windows-latest:host,windows:host),
-InstallDir (défaut C:\ci), -RustVersion (défaut = RUST_VERSION de .github/workflows/tauri.yml : les garder égaux),
-RunnerVersion, -SkipBuildTools, -ReRegister, -Uninstall (-Purge : aussi le dossier).
Installé depuis les seules sources officielles (la vérification entre parenthèses) :
| Outil | Source |
|---|---|
Git for Windows (son bash exécute les étapes) |
releases GitHub de git-for-windows (SHA-256 publié) |
| Visual Studio 2022 Build Tools : outils C++ x64 + SDK Windows 11, rien d'autre | aka.ms/vs/17/release/vs_BuildTools.exe (pas de somme publiée : la signature Authenticode de Microsoft est vérifiée) |
Rust, la version du workflow, à l'échelle de la machine (RUSTUP_HOME=C:\rust\rustup, CARGO_HOME=C:\rust\cargo) |
static.rust-lang.org (SHA-256 de rustup-init) |
Node.js LTS (les actions JavaScript comme actions/checkout) |
nodejs.org/dist (SHA-256 de SHASUMS256.txt) |
| forgejo-runner | code.forgejo.org ne publie aucun binaire Windows (Linux seulement, vérifié le 2026-11-07) : le script compile le tag de la release avec Go (go.dev, SHA-256 vérifié), puis supprime Go. Si un binaire Windows avec somme apparaît, il le télécharge. |
Puis il enregistre le runner (mode hôte : les jobs tournent directement sur la machine, sans conteneur) et crée la tâche planifiée
ForgejoRunner-<nom> : au démarrage, en SYSTEM, relancée en cas d'échec, avec le bash de Git en premier dans le PATH
(voir Dépannage). Il affiche un récapitulatif et attend la ligne « declared successfully ».
Idempotent : relancé, il ne fait que ce qui manque. Première fois : 20 à 60 minutes. Redémarrage : seulement si l'installeur Visual
Studio le demande (le script le dit ; le runner démarre ensuite tout seul). Retirer : .\install-windows-runner.ps1 -Uninstall -Name bureau-pc
puis supprimer le runner dans la forge. Les outils restent. Un portable ne doit pas se mettre en veille.
4. Windows, jobs Linux (builds JumPHP, Android, tests)
tools/runner/install-wsl-linux-runner.ps1, en administrateur, Windows 10 2004+ ou
11, virtualisation activée dans le BIOS. Pas de Docker Desktop : Docker Engine est installé dans WSL2.
$env:JUMPHP_RUNNER_TOKEN = '<jeton>'
.\install-wsl-linux-runner.ps1 -Scope user/<login> -Name alice-pc
Il active WSL et la plateforme de machine virtuelle, installe Ubuntu-24.04 sans l'ouvrir (utilisateur jumphp, systemd dans
/etc/wsl.conf), installe Docker Engine depuis le dépôt apt officiel de Docker (clé vérifiée contre l'empreinte publiée), clone
JumPHP dans la distribution, y lance bin/jumphp runner:install --scope ... --name ..., et crée la tâche JumphpWslRunner-<nom>
qui garde la distribution vivante (sans processus, WSL l'arrête, et le runner avec).
Redémarrages. La première fois, activer WSL demande en général un redémarrage de Windows : le script s'arrête (code 3010) et le dit.
Redémarrez, ouvrez PowerShell en administrateur et relancez la même commande : il reprend où il s'était arrêté (le jeton n'est jamais
conservé : redéfinissez JUMPHP_RUNNER_TOKEN ; une fois le runner enregistré, plus besoin de jeton).
Options : -Distro, -LinuxUser, -Memory 8GB -Processors 4 (écrits dans %USERPROFILE%\.wslconfig ; WSL2 prend la moitié de la RAM par
défaut), -Labels, -RunAtBoot, -Uninstall (-RemoveDistro supprime la distribution et tout son contenu).
Au logon ou au boot. Une distribution WSL appartient à un utilisateur Windows : la tâche tourne donc sous votre compte, par défaut à
l'ouverture de session (le runner est arrêté tant que personne n'est connecté). -RunAtBoot demande votre mot de passe Windows (gardé par
le Planificateur de tâches, pas par le script) et démarre au boot.
5. Linux, jobs Windows : une VM Windows sans écran
Pour la bibliothèque Windows du runtime Tauri depuis Linux. tools/runner/windows-vm/ crée une VM
Windows 10 avec QEMU/KVM (installation automatique, pilotes virtio, sans fenêtre), puis y installe la section 3 :
cd tools/runner/windows-vm
./create-vm.sh --iso ~/Téléchargements/Win10_22H2.iso --dir ~/windows-ci-vm --locale fr-FR --timezone "Romance Standard Time"
export JUMPHP_RUNNER_TOKEN=<jeton>
./provision.sh --dir ~/windows-ci-vm --scope org/<nom> --name win-vm
./start-vm.sh --dir ~/windows-ci-vm [start|stop|status]
- Windows demande une licence que vous possédez. Téléchargez l'ISO vous-même chez Microsoft (https://www.microsoft.com/software-download/windows10ISO) ; les scripts ne téléchargent aucun Windows et n'en fournissent pas. Les ISO d'évaluation expirent (l'une s'installe déjà expirée) : prenez l'ISO multi-éditions. Windows 10 n'a plus de mises à jour de sécurité gratuites : la VM doit rester jetable.
- Les ports RDP / SSH de la VM sont liés à
127.0.0.1; PowerShell est piloté par l'agent invité QEMU (guest-exec.py, sans SSH). Le jeton entre dans l'invité par l'agent (dossier privé, supprimé aussitôt), jamais en ligne de commande. - Il faut
/dev/kvm, 8 Go de RAM, 80 Go de disque. Détails : le README du dossier.
6. Comment un projet choisit son runner
Par les labels de runs-on:. Un job attend qu'un runner de son périmètre ait tous les labels.
| Label | Posé par | Tourne dans |
|---|---|---|
ubuntu-latest, ubuntu-22.04 |
runner:install, script WSL2 |
un conteneur Docker (node:20-bookworm) |
windows-latest, windows |
install-windows-runner.ps1 (mode hôte) |
directement sur la machine (labels :host) |
jobs:
linux: { runs-on: ubuntu-latest, steps: [ ... ] }
windows:
if: github.server_url != 'https://github.com' # sur GitHub, windows-latest est celui de GitHub
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- shell: bash # le bash de Git for Windows
run: ...
Votre propre label : -Labels mon-gpu:host (script Windows) ou --labels mon-gpu:docker://image (runner:install), puis runs-on: mon-gpu.
Les workflows vivent dans .github/workflows/. Ne créez pas .forgejo/workflows/ : Forgejo le lit à la place de .github/workflows
quand il existe, et tous les autres workflows cesseraient de tourner sans bruit.
Exemple réel : .github/workflows/tauri-windows.yml (runs-on: windows-latest, forge seulement) construit jumphp_tauri.dll et le publie
comme asset jumphp_tauri-windows-x86_64.dll de la release tauri-<clé> (bash tools/tauri-key.sh | sha256sum | cut -c1-16) que
bin/jumphp tauri:download windows-x86_64 et app:export <app> --windows téléchargent. Il publie avec le github.token du job (ou un secret
FORGE_TOKEN). Son dossier Cargo est C:/ci/target-tauri (conservé : builds incrémentaux), d'où -InstallDir = C:\ci par défaut.
7. Un projet sur GitHub, et les runners self-hosted GitHub
Ses workflows utilisent les runners de GitHub (ubuntu-latest, macos-15, windows-latest) avec les minutes de votre compte, ou votre
propre runner self-hosted GitHub (Settings > Actions > Runners > New self-hosted runner : GitHub donne les commandes). Les scripts
JumPHP ci-dessus concernent les runners Forgejo ; côté GitHub :
- Windows :
config.cmd --url ... --token ...puissvc.cmd install; installer les mêmes outils (Git, Build Tools, Rust, Node) comme le fait la première moitié deinstall-windows-runner.ps1;runs-on: [self-hosted, windows]. - Linux :
config.shetsvc.sh install;runs-on: [self-hosted, linux]. - Jamais de runner self-hosted sur un dépôt public dont n'importe qui peut ouvrir des pull requests : le workflow d'un fork tournerait chez vous. Même règle pour la forge.
Les commandes gh de bin/jumphp (android, apple, installer, release) marchent sur les deux : tools/bin/gh est le vrai gh pour GitHub et
parle à l'API de git.jumphp.net sinon.
8. Sécurité (à lire)
- Un seul utilisateur ou une seule organisation, jamais l'instance.
- Un runner exécute le code des workflows de son périmètre. Qui peut pousser un workflow dans un dépôt de ce propriétaire (ou dont une pull request déclenche un workflow) peut exécuter des commandes sur le runner. N'enregistrez des runners que pour des propriétaires de confiance.
- Le mode hôte (script Windows) n'isole rien : les jobs tournent en SYSTEM sur la machine, avec tous ses fichiers et son réseau. Utilisez une
VM jetable (section 5) ou une machine sans rien de précieux : pas de données personnelles, pas d'identifiants enregistrés, pas d'accès à vos
autres machines. Les runners Linux isolent les jobs dans des conteneurs d'un Docker propre (
dindprivilégié : ne pas l'exposer à des inconnus). - Les jetons ne sont pas conservés : les scripts les prennent dans l'environnement (ou une saisie masquée), les utilisent une fois, ne les
écrivent ni dans un fichier ni dans un journal. Le runner garde son propre identifiant (
<InstallDir>\runner\.runner, lisible des seuls administrateurs et SYSTEM ;~/.jumphp/runners/<nom>/data/.runner) : c'est un secret. - Révoquer : supprimer le runner dans la forge (Paramètres > Actions > Runners) ; puis
-Uninstall/runner:removesur la machine, ou supprimer la VM. - Les secrets d'un dépôt sont donnés à ses jobs : un runner partagé avec les workflows d'autrui peut les lire. Un runner par niveau de confiance.
- Un runner travaille tant que sa machine est allumée ; les jobs attendent dans la file sinon.
9. Dépannage
| Symptôme | Cause / remède |
|---|---|
Erreurs bash bizarres sous Windows, ou « WSL n'a pas de distribution » |
C:\Windows\System32\bash.exe est le stub WSL. run.ps1 met C:\Program Files\Git\bin en tête du PATH ; si vous lancez le runner autrement, faites-en autant. |
| Une étape meurt sans message sous Windows | shell: bash tourne avec -e : un grep sans résultat termine l'étape. Ajouter ` |
Les sha256sum diffèrent entre Windows et Linux |
Git for Windows affiche hash *fichier : ne garder que le premier champ. |
| Le hash de fichiers extraits diffère (une clé calculée dessus) | Git for Windows a converti LF en CRLF : git config core.autocrlf false puis git checkout HEAD -- <fichiers> (fait dans tauri-windows.yml). |
| Le workflow ne tourne pas | un dossier .forgejo/workflows/ existe (il remplace .github/workflows) ; ou le push ne touche pas les paths: ; ou aucun runner du périmètre n'a tous les labels. |
| « no matching runner » / le job attend | runner hors ligne, mauvais périmètre (un runner user/ ne sert pas une organisation), label manquant. |
registration failed |
jeton déjà utilisé ou d'un autre périmètre : en refaire un. Vérifier -Instance. |
| Une relance n'a rien fait | normal (idempotent). -ReRegister (Windows) / -Uninstall puis relancer pour repartir de zéro. |
| Build Tools : code 3010 | redémarrage nécessaire ; le runner repart seul. 1618 : un autre installeur tourne. Journaux : %TEMP%\dd_*.log. |
PowerShell : NativeCommandError sur la sortie de rustup / git / go |
PowerShell traite stderr comme une erreur avec $ErrorActionPreference='Stop' ; les scripts encadrent les programmes natifs. |
generate-config illisible (Windows) |
le > de PowerShell 5.1 écrit en UTF-16 ; utiliser cmd /c "... > fichier" (le script le fait). |
| WSL : le runner s'arrête à la fermeture du terminal | la tâche de maintien est absente : Get-ScheduledTask JumphpWslRunner-*, Start-ScheduledTask. |
| WSL : systemd ne tourne pas | /etc/wsl.conf doit contenir [boot] systemd=true ; wsl --shutdown, relancer le script. |
| VM Windows : agent injoignable | VM éteinte ou Windows en démarrage ; ./start-vm.sh status. |
| VM Windows : l'installation ne finit pas | la langue de l'ISO doit correspondre à --locale ; l'édition doit exister dans l'ISO (--image-index). |
| Disque plein | dossiers target de Rust (C:\ci\target-tauri), images Docker (docker system prune). |
Journaux : Windows <InstallDir>\runner\runner.log ; Linux docker compose -f ~/.jumphp/runners/<nom>/compose.yaml logs -f ; WSL
wsl -d Ubuntu-24.04 -u jumphp -- docker logs jumphp-runner-<nom>-runner-1.
Construire le micro PHP (workflow
standalone) sur ces runners, et ce que les images de GitHub donnaient gratuitement : ci-standalone.fr.md.
10. Pour les agents IA
On peut vous demander « installe un runner sur ma machine ». Faites ceci, et rien d'autre :
- Demandez d'abord. Dites ce que vous allez installer (Git, Visual Studio Build Tools ~5 Go, Rust, Node, un runner, WSL, une VM...), où, et que cela demande les droits administrateur et de longs téléchargements. N'installez rien avant un oui.
- Jamais de runner d'instance. Le périmètre est UN utilisateur ou UNE organisation que l'utilisateur nomme ; demandez, ne devinez pas.
- Jetons : l'utilisateur crée le jeton dans la forge et vous le donne dans une variable d'environnement (
JUMPHP_RUNNER_TOKEN) ou le saisit dans son terminal. Ne l'écrivez jamais dans un fichier, un commit, une note, un argument de script ou votre réponse ; jamais dansAGENTS.md, un.envversionné ou un workflow. S'il apparaît dans votre contexte, ne le répétez pas. - Donnez à l'utilisateur les commandes exactes (il les lance en administrateur dans son terminal : vous ne pouvez pas élever pour lui) et expliquez
les redémarrages et le « relancer la même commande ». Préférez les scripts de
tools/runner/à l'improvisation. - Prévenez que le mode hôte n'isole rien (proposez une VM jetable) ; prévenez de la licence Windows pour le kit VM et ne téléchargez jamais Windows d'une source non officielle.
- Ne touchez pas aux runners qui ne sont pas à l'utilisateur ; ne supprimez pas de runner dans la forge sans demande.
- À la fin, vérifiez « Idle » dans la liste des runners (ou le récapitulatif du script) et dites comment retirer le runner.
11. Ce qui a été testé, et ce qui ne l'a pas été
| Élément | Testé | Comment |
|---|---|---|
install-windows-runner.ps1 |
oui | sur une VM Windows 10 22H2 qui avait déjà les outils : enregistrement, connexion, relance (idempotence), -Uninstall ; sur une VM fraîchement installée par le kit windows-vm : l'installation complète. PowerShell 5.1. |
windows-vm/* |
oui | create-vm.sh avec une ISO Windows 10 Pro française sur un hôte Debian KVM, puis provision.sh ; start-vm.sh, guest-exec.py |
install-wsl-linux-runner.ps1 |
en partie | syntaxe PowerShell vérifiée ; les parties Linux (édition de wsl.conf, dépôt apt et empreinte de clé Docker, clonage) exécutées dans un conteneur Ubuntu 24.04. Jamais lancé sur un vrai Windows avec WSL : activation de WSL, wsl --install --no-launch, repli du premier lancement, jeton par WSLENV, sg docker, tâche planifiée, -RunAtBoot non testés. Prévoir de petites corrections. |
| Windows 11, Windows ARM64, Windows Server | non | |
| Runner macOS | pas de script |
Les runners du mainteneur (un exemple)
Le runner Linux du PC du mainteneur est enregistré pour l'organisation jumphp seule ; les releases du moteur et du runtime sont construites en
local (bin/jumphp engine:pack, runtime:build) et publiées avec gh release create vX.Y.Z .build/jumphp-engine.tar.gz .... Le runner Windows
win10-vt2 est une VM Windows 10 (4 vCPU, 5 Go) sur le même PC, installée exactement comme la section 3.