Guide de configuration CI pour les équipes

Configurez votre runner avec ce guide

Ce Mac mini Apple Silicon M4 exécute uniquement les tâches de votre équipe. Vérifiez d’abord l’instance et la connexion, enregistrez ensuite le runner, puis fixez la chaîne d’outils Xcode. Traitez chaque problème à l’étape concernée, sans refaire tout le pipeline.

Louer un nœud de build Voir les instances existantes

Pour une commande existante, vérifiez l’état dans la console. Ne publiez pas les jetons d’enregistrement, mots de passe SSH ni éléments de signature dans des journaux accessibles à tous.

De la commande à la connexion

Prenez en main le nœud en quatre étapes

Comptez environ 4 minutes entre la confirmation du paiement et la récupération puis la vérification des identifiants de connexion. Ces durées sont indicatives et n’incluent ni la confirmation de la passerelle de paiement, ni les nouvelles tentatives réseau, l’installation de dépendances ou l’enregistrement du runner. L’avancement réel est celui indiqué dans la console.

Vérifier la commande confirmée
Environ 30 s

Dans la console, vérifiez que la commande est payée et que le modèle, la durée et le nœud correspondent à votre achat. Merge M4 S dispose de 16GB RAM / 256GB SSD ; Merge M4 L, de 24GB RAM / 512GB SSD. Les deux modèles utilisent Apple Silicon M4.

Bloqué ? Vérifiez d’abord l’état de la facture. Si la page n’est pas encore à jour, ne payez pas une deuxième fois. Notez le numéro de commande, puis consultez l’historique des paiements dans la section Facturation de cette page.
Vérifier l’attribution du nœud physique
Environ 2 min

Ouvrez les détails de l’instance associée à la commande et attendez que le système affiche son état et ses informations de connexion. Chaque machine est attribuée à un seul client et n’est pas virtualisée ; la planification des tâches de votre équipe est gérée par le runner que vous configurez.

Bloqué ? Notez l’ID de l’instance, le numéro de commande et son état actuel, puis ouvrez un ticket depuis la console. Ne confondez pas « facture payée » et « identifiants de l’instance générés ».
Récupérer les identifiants de connexion
Environ 1 min

Dans les détails de l’instance, relevez l’adresse SSH, le port, le nom d’utilisateur et les informations de connexion VNC. Utilisez les valeurs indiquées pour chaque champ : ne devinez pas le port par défaut et ne réutilisez pas l’adresse ou le mot de passe d’une ancienne instance.

Bloqué ? Vérifiez que le compte connecté est bien propriétaire de la commande et que vous consultez la bonne instance. Pour le ticket, indiquez uniquement l’ID de l’instance et le nom du champ manquant ; n’envoyez pas le mot de passe complet.
04
Tester une connexion à distance
Environ 30 s
SSH sert à lancer des builds en ligne de commande, à enregistrer un runner et à synchroniser des fichiers. VNC donne accès à l’interface graphique Xcode, au simulateur et à la configuration interactive. Vous pouvez utiliser l’interface graphique macOS et la ligne de commande, séparément ou ensemble.
```
ssh -p "$SSH_PORT" "$SSH_USER@$SSH_HOST"
uname -m
sw_vers
```
Lors de la première connexion, vérifiez l’empreinte de l’hôte. Une fois connecté, vérifiez que l’architecture indiquée est arm64. En cas de délai d’attente, vérifiez l’adresse, le port et votre réseau local. En cas d’échec d’authentification, vérifiez le nom d’utilisateur et les identifiants. Ne désactivez pas la vérification de l’identité de l’hôte pour contourner une empreinte inattendue.

Dans le client VNC, utilisez les champs correspondants indiqués dans les détails de l’instance ; ne réutilisez pas directement le port SSH. Si la connexion fonctionne mais que l’affichage est lent, réduisez d’abord la résolution. Les builds automatisés peuvent continuer à s’exécuter en SSH.

Vérifier l’instance et les identifiants Consulter le guide de connexion à distance

Conserver votre CI actuelle

Dirigez explicitement les tâches vers ce M4

Dans votre plateforme CI, ouvrez la page d’ajout d’un runner ou d’un agent pour récupérer le programme d’installation et la commande d’enregistrement, puis exécutez-les sur le nœud. Voici les points essentiels de l’enregistrement : la plateforme génère l’URL de l’organisation, le jeton et le répertoire de travail ; ne reprenez pas les variables d’exemple telles quelles. Après l’installation, lancez une tâche de test sans éléments de signature.

GitHub Actions

Dans les paramètres du dépôt ou de l’organisation, ajoutez un self-hosted runner et choisissez le paquet macOS ARM64. Décompressez-le, exécutez la commande de configuration fournie par la plateforme dans le répertoire du runner, puis démarrez le processus.

./config.sh \
  --url "$RUNNER_URL" \
  --token "$RUNNER_TOKEN" \
  --labels macos-m4
./run.sh

Dans le workflow, indiquez runs-on: [self-hosted, macOS, ARM64, macos-m4]et vérifiez que le tag correspond au résultat de l’enregistrement. Les tags servent au routage ; ils n’isolent pas automatiquement les tâches sur la machine.

Vérification : la plateforme indique que le runner est en ligne et, pour la tâche de test, uname -m renvoie arm64. Pour un fonctionnement permanent, configurez le service conformément à la documentation du programme d’installation et exécutez-le avec le même utilisateur que celui des builds.

Tag conseillé : macos-m4

GitLab Runner

Créez un runner au niveau du projet ou du groupe et récupérez le jeton d’authentification utilisé par la version actuelle. Installez la version ARM64, enregistrez le runner et choisissez l’exécuteur shell pour exécuter les tâches dans l’environnement macOS de l’utilisateur de build.

gitlab-runner register
gitlab-runner verify
gitlab-runner run

Dans la plateforme, attribuez au runner le tag macos-m4 et indiquez la même valeur dans le champ tags . Lors de l’enregistrement interactif, saisissez l’URL et le jeton fournis par la plateforme. Ne stockez pas le jeton dans le dépôt.

Vérification : le runner est associé au bon projet et les tâches passent à l’état d’exécution. Si elles restent en attente, contrôlez les tags, la configuration des branches protégées et les autorisations du runner pour le projet, puis vérifiez la charge de la machine.

Exécuteur conseillé : shell

Agent Jenkins

Créez un nœud dédié et définissez son répertoire de travail distant ainsi que le tag macos-m4 . Installez une version de Java compatible selon les indications du contrôleur, téléchargez le fichier agent fourni et utilisez les paramètres de lancement qu’il génère.

java -jar agent.jar \
  -url "$JENKINS_URL" \
  -secret "$AGENT_SECRET" \
  -name "$AGENT_NAME" \
  -webSocket \
  -workDir "$AGENT_WORKDIR"

Dans le pipeline, indiquez agent { label 'macos-m4' }. L’utilisateur de build doit pouvoir écrire dans le répertoire de travail. La version de Java doit répondre aux exigences du contrôleur : vérifiez aussi l’environnement de l’agent, pas seulement le lancement de Java dans votre terminal local.

Vérification : le contrôleur indique que le nœud est en ligne et l’espace de travail se trouve dans le répertoire attendu. Commencez par établir une référence avec un seul exécuteur, puis évaluez la concurrence en fonction de la mémoire, du disque et de la charge des tests.

Établir d’abord une référence avec une seule tâche

Une machine dédiée évite de partager le CPU avec d’autres clients, mais ne supprime pas la file d’attente interne de votre équipe. Si un même runner exécute plusieurs tâches à la fois, vous devez toujours gérer la concurrence et isoler les espaces de travail et les éléments de signature.

Garantir un environnement reproductible

Utilisez la même version de Xcode en local et en CI

Le message « la compilation fonctionne dans le terminal, mais pas sur le runner » signale souvent une différence de chemin de la chaîne d’outils ou d’utilisateur d’exécution. Commencez par noter la version actuelle, choisissez la chaîne d’outils, puis installez les runtimes de simulateur nécessaires. Ne réinstallez pas Xcode d’emblée.

Noter la version avant tout changement

Vous pouvez installer plusieurs versions de Xcode dans des répertoires d’applications distincts. Commencez par relever le système, le répertoire de développement actif et la version des outils de build avec les commandes ci-dessous, puis comparez les résultats aux exigences du projet.

sw_vers
xcode-select -p
xcodebuild -version
xcrun --find swift

Pour modifier la valeur par défaut de toute la machine, utilisez xcode-select. Avant de changer de version, vérifiez qu’aucun autre build n’est en cours, puis contrôlez le résultat avec l’utilisateur qui exécute la CI.

sudo xcode-select --switch \
  /Applications/Xcode.app/Contents/Developer
xcodebuild -version

Choisir la version par tâche et télécharger selon les projets

Si votre équipe utilise plusieurs versions de Xcode, définissez de préférence DEVELOPER_DIRpour chaque tâche afin de limiter les effets des changements globaux. Remplacez le chemin d’exemple par celui de la version réellement installée sur le nœud.

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcodebuild -version
xcrun simctl list runtimes
xcrun simctl list devices available
df -h

Téléchargez les runtimes de simulateur depuis les réglages Xcode en fonction des besoins du projet. Les runtimes, les données des simulateurs et DerivedData occupent de l’espace disque. Vérifiez l’espace disponible avant l’installation et ne conservez que les versions utilisées par l’équipe.

Des commandes disponibles ne garantissent pas que toutes les dépendances du projet sont installées. Avec le même utilisateur, vérifiez Ruby, CocoaPods, le gestionnaire de paquets et les fichiers de verrouillage du projet. Lors de la première installation, confirmez les invites dans un environnement interactif.

Avant le premier build, vérifiez ces trois points dans l’environnement d’exécution du runner
Élément à vérifier	Commande ou emplacement	Critère de validation
Chemin de la chaîne d’outils	`xcode-select -p` et variables d’environnement de la tâche	Le chemin pointe vers la version de Xcode prévue par le projet et la version affichée est conforme aux attentes
Utilisateur d’exécution	`whoami`et`printf '%s\n' "$HOME"`	L’utilisateur de build, le répertoire personnel et le propriétaire du trousseau sont identiques
Espace de travail et disque	`pwd`et`df -h`	L’espace de travail est accessible en écriture et dispose de suffisamment d’espace pour les dépendances, les fichiers temporaires et les archives

Employer les mêmes termes dans l’équipe

Huit termes pour clarifier les responsabilités

Distinguez la machine, le mode de connexion et la planification des tâches pour décrire précisément le niveau où survient un problème.

Nœud physique: Mac mini qui héberge macOS et les tâches de build. Les informations de connexion dans les détails de l’instance correspondent au nœud que vous louez.
Dédié: La machine entière est attribuée à un seul client et son CPU n’est pas partagé avec d’autres clients. Votre équipe doit toutefois gérer ses propres tâches concurrentes.
Non virtualisé: Vous disposez d’un environnement macOS sur un Mac physique dédié, et non d’une instance virtuelle créée sur un hôte partagé.
VNC: Mode de connexion permettant d’afficher et de contrôler à distance l’interface graphique de macOS, notamment pour Xcode, les simulateurs et la configuration interactive.
SSH: Connexion chiffrée en ligne de commande, utile pour lancer des builds, gérer des processus et transférer des fichiers avec les outils adaptés.
self-hosted runner: Programme CI enregistré et géré par l’équipe sur son propre nœud. Il récupère les tâches auprès de la plateforme CI et les exécute.
Apple Silicon: Architecture des puces Apple utilisées dans les Mac. Les deux modèles proposés utilisent M4 ; vérifiez la compatibilité arm64 des dépendances et du programme d’installation du runner.
Connexion Thunderbolt 5 en chaîne: Option de connexion facturée par machine dans le répertoire. Elle ne regroupe pas automatiquement le CPU ou la mémoire de plusieurs machines en une seule : vous devez toujours orchestrer les charges de travail.

Conservez les journaux avant de modifier l’environnement

Rétablir le build en ciblant la couche concernée

Enregistrez d’abord la commande en échec, son code de sortie et la première erreur pertinente, puis ne modifiez qu’un seul paramètre avant de relancer. Si vous changez Xcode, effacez le cache et réenregistrez le runner en même temps, vous ne saurez pas quelle action a résolu le problème.

Échec de signature : vérifiez d’abord l’utilisateur et le trousseau

Distinguez d’abord un échec de compilation d’un échec de signature. Vérifiez le certificat, sa clé privée associée, le profil de provisionnement et leurs dates de validité uniquement si l’erreur survient pendant l’archivage ou la signature. L’équipe doit configurer ces éléments conformément aux exigences du projet.

whoami
security list-keychains -d user
security find-identity -v -p codesigning

Si la signature fonctionne dans l’interface graphique mais échoue en CI, vérifiez que le runner est lancé par le même utilisateur, que le trousseau cible figure dans la liste de recherche et que le processus non interactif dispose des autorisations requises. Si le trousseau doit être déverrouillé, injectez les identifiants via les secrets protégés de la CI. Ne mettez jamais le mot de passe dans un script, l’historique des commandes ou les journaux.

Après l’importation du certificat, vérifiez que le profil de provisionnement correspond à la bonne équipe, à l’identifiant de l’app et à la configuration de build. Pour un ticket, joignez un message d’erreur expurgé ; ne transmettez ni clé privée, ni mot de passe de certificat, ni éléments de signature complets.

Cache défectueux : limitez le nettoyage à un seul projet

Relancez d’abord le même commit et notez la version de Xcode. Si la résolution d’une seule dépendance échoue, vérifiez le fichier de verrouillage, la version de la dépendance et l’erreur de téléchargement. Vider tous les caches à répétition ne résout pas un problème réseau.

Définissez un chemin DerivedData propre au projet afin de pouvoir reconstruire uniquement ses artefacts. La commande ci-dessous s’utilise dans un espace de travail existant et distinct. Avant de l’exécuter, remplacez les variables par des chemins réels et par un schéma partagé.

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -derivedDataPath "$PROJECT_DERIVED_DATA" \
  clean build

clean augmente la charge du prochain build. Ne partagez pas un même répertoire de cache accessible en écriture entre plusieurs tâches. Avant de le nettoyer ou de le déplacer, arrêtez les tâches qui l’utilisent.

Disque saturé : distinguez caches, runtimes et artefacts

Vérifiez d’abord l’espace libre, puis l’espace occupé par DerivedData, les archives et les données des simulateurs. Ne lancez pas de suppression récursive dans tout le répertoire utilisateur et ne supprimez pas d’artefacts pendant l’envoi d’une archive.

df -h
du -sh "$HOME/Library/Developer/Xcode/DerivedData"
du -sh "$HOME/Library/Developer/Xcode/Archives"
du -sh "$HOME/Library/Developer/CoreSimulator"

Après avoir arrêté les tâches concernées, supprimez les caches de projets inutilisés, désinstallez dans Xcode les runtimes superflus et gérez les anciennes archives sauvegardées selon les règles de conservation de l’équipe. Sauvegardez séparément le projet, les éléments de signature et les artefacts de publication.

Si vous prévoyez un besoin d’espace durable, vous pouvez choisir une option SSD supplémentaire de +1TB ou +2TB lors de la commande. Plus de stockage n’ajoute pas de mémoire : vérifiez d’abord que le goulot d’étranglement vient bien du disque et non du nombre de tâches simultanées.

Runner hors ligne : vérifiez successivement la connexion, le processus et les autorisations

Vérifiez d’abord que le nœud est accessible en SSH, puis contrôlez le processus du runner et ses journaux. Si le nœud est en ligne mais que la plateforme CI indique que le runner est hors ligne, vérifiez si le processus s’est arrêté, si le contrôleur CI est joignable et si le jeton ou les autorisations du nœud ont changé.

Lancez une fois le runner au premier plan et conservez la première erreur de connexion. S’il fonctionne au premier plan mais s’arrête à la fermeture du terminal, configurez un service permanent en suivant la documentation du runner. Le service doit s’exécuter avec le même utilisateur que celui configuré pour la chaîne d’outils, le répertoire de travail et le trousseau.

Avant de redémarrer, vérifiez qu’aucune tâche d’archivage ou d’envoi n’est en cours afin de ne pas interrompre la production des artefacts. Si la plateforme indique que le runner est en ligne mais que les tâches restent en file d’attente, vérifiez les tags, les droits sur les branches et les limites de concurrence au lieu de supprimer puis de réenregistrer le runner à répétition.

Si vous utilisez plusieurs groupes ou pools d’instances, attribuez aux nœuds des tags explicites, par exemple macos-m4-build et macos-m4-release, afin que les tâches de publication soient dirigées uniquement vers les nœuds configurés avec l’environnement de signature correspondant.

Vérifiez la transaction avant de réessayer

Associez chaque paiement à la bonne commande

Facturation à la journée, à la semaine, au mois ou au trimestre, avec règlement en dollars américains (USD). Les seuls moyens de paiement acceptés sont USDT-TRC20 et les cartes Visa / Mastercard / Amex traitées par Stripe. Les options disponibles sont celles indiquées par l’interface de paiement.

Transfert USDT-TRC20 effectué, commande toujours en attente de confirmation

Vérifiez un à un le réseau, l’adresse de réception et le montant indiqués sur la page de paiement de la commande. Un transfert effectué ne signifie pas que la commande est confirmée : vérifiez l’état de la transaction sur la blockchain et celui de la facture dans la console.

Ne faites pas un deuxième transfert pour accélérer la confirmation et n’utilisez pas les informations de paiement d’une autre commande. Notez le numéro de commande, le hash de transaction, le montant et l’heure du transfert, puis communiquez ces informations dans un ticket depuis la console. N’envoyez ni clé de portefeuille ni phrase de récupération.

Si vous avez quitté la page de paiement, retournez d’abord à la même commande pour vérifier son état avant de reprendre le paiement et éviter de payer deux fois le même service.

Paiement par carte non abouti : vérifiez l’authentification et la réponse de la banque

Vérifiez l’exactitude des informations de carte et de facturation, le solde disponible et la validation de l’authentification par la banque. Si une page de redirection est bloquée, autorisez son ouverture pour le paiement en cours, puis vérifiez la commande.

En cas de refus, conservez le résumé de l’erreur et contactez votre banque pour vérifier les restrictions applicables à la transaction. Évitez les tentatives successives rapprochées. Si la banque indique que le paiement a été débité alors que la commande n’est pas confirmée, demandez d’abord une vérification par ticket avant de payer à nouveau.

Pour le ticket, indiquez le numéro de commande, l’heure de l’incident et joignez une capture d’écran expurgée de l’erreur. Nous n’avons besoin ni de votre numéro de carte complet, ni du cryptogramme, ni du code de vérification bancaire.

Avant de renouveler, vérifiez l’instance, la durée et la date d’expiration

Dans la console, ouvrez l’abonnement ou la facture correspondant à l’instance et vérifiez son ID, sa date d’expiration et la durée à régler avant de payer. Créer une nouvelle commande et renouveler une instance existante sont deux opérations distinctes : ne vous fiez pas au seul nom du modèle.

Le renouvellement est confirmé par l’état de la facture et de l’instance ; ne présumez pas qu’il est automatique. Avant l’expiration, sauvegardez les projets, les caches et les artefacts de publication. L’effacement du disque après la libération de l’instance ne remplace pas une sauvegarde récupérable.

Les nœuds fonctionnent normalement 365 jours par an. Si votre demande concerne la disponibilité du service, indiquez l’ID de l’instance, la période concernée et l’erreur de connexion pour faciliter la vérification. Ne confondez pas l’arrêt volontaire d’un processus par un utilisateur avec l’indisponibilité du nœud.

Fournissez des informations reproductibles

Transmettez les détails du problème au support

Pour un problème sur une instance existante, ouvrez un ticket depuis la console et indiquez l’ID de l’instance, la date et le fuseau horaire, les étapes en échec, le résultat attendu et des journaux expurgés. Pour démarrer plusieurs machines ou planifier un pool de runners, détaillez votre besoin sur la page de contact ou écrivez à support@vpsmerge.com.

N’envoyez ni mot de passe, ni jeton d’enregistrement, ni clé privée, ni données de paiement complètes. Une seule erreur pertinente facilite davantage le diagnostic qu’un écran entier de journaux répétés.

Ouvrir un ticket dans la console Préparer votre demande pour l’équipe