winzik/docs/ci-runner.fr.md

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) : le docker.sock de 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 ... puis svc.cmd install ; installer les mêmes outils (Git, Build Tools, Rust, Node) comme le fait la première moitié de install-windows-runner.ps1 ; runs-on: [self-hosted, windows].
  • Linux : config.sh et svc.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 (dind privilé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:remove sur 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 :

  1. 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.
  2. Jamais de runner d'instance. Le périmètre est UN utilisateur ou UNE organisation que l'utilisateur nomme ; demandez, ne devinez pas.
  3. 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 dans AGENTS.md, un .env versionné ou un workflow. S'il apparaît dans votre contexte, ne le répétez pas.
  4. 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.
  5. 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.
  6. Ne touchez pas aux runners qui ne sont pas à l'utilisateur ; ne supprimez pas de runner dans la forge sans demande.
  7. À 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.