Commencez par le symptôme

Décomposez les problèmes de connexion et de build en étapes vérifiables

Vous n’avez pas besoin de lire tout le guide avant de commencer. Choisissez un point d’entrée — connexion, environnement, automatisation, réseau ou stockage — puis vérifiez successivement l’adresse, les autorisations, les versions des outils et les journaux. Chaque étape indique le résultat attendu pour savoir s’il faut poursuivre le diagnostic ou ouvrir un ticket.

Voir les points de diagnostic Ouvrir un ticket dans la console
6 catégories Points d’entrée de la documentation
2 options Modes de connexion à distance
5 parcours Parcours de décision par symptôme
Index de la documentation

Choisissez la tâche que vous êtes en train d’effectuer

Chaque point d’entrée renvoie à des vérifications précises sur cette page. Ne modifiez qu’une variable à la fois et notez les commandes, versions et résultats avant et après chaque changement.

Première connexion Préparez vos identifiants, vérifiez l’empreinte de l’hôte, remplacez les clés et fermez correctement la session. CONNECT Environnement de développement Vérifiez le chemin de Xcode, les cibles de build, la résolution des dépendances et l’emplacement des archives de journaux. TOOLCHAIN Build automatisé Enregistrez le self-hosted runner et planifiez les labels, la concurrence et le répertoire de travail. RUNNER Accès réseau Utilisez les journaux détaillés pour distinguer une erreur d’adresse, un port inaccessible, un délai d’attente et un échec d’authentification. NETWORK Gestion du stockage Identifiez l’espace occupé par DerivedData, les caches, les archives et les répertoires de travail. STORAGE Résolution des incidents Entrez dans l’arbre de décision selon l’une des cinq catégories de symptômes pour obtenir la prochaine action vérifiable. RESOLVE
Principe de diagnostic : Ne mettez pas simultanément Xcode à niveau, ne remplacez pas les dépendances, ne changez pas de réseau et ne modifiez pas la configuration de signature. Une seule modification à la fois permet d’identifier la véritable cause.
Connexion à distance

SSH et VNC suivent des parcours de vérification différents

SSH convient à la ligne de commande, à l’automatisation et au transfert de fichiers ; VNC convient aux tâches nécessitant l’interface graphique de macOS. Dans les deux cas, vérifiez d’abord l’adresse du nœud, puis les identifiants.

Parcours en ligne de commande

Vérification de la connexion SSH

  1. 01
    Préparer les informations de connexion

    Vérifiez l’adresse de l’hôte, le port, le nom d’utilisateur et le mode d’accès temporaire dans les informations de livraison de la commande. Ne copiez pas une adresse susceptible d’avoir changé depuis l’historique d’un ancien terminal.

  2. 02
    Effectuer la première vérification

    Lancez d’abord une connexion en mode détaillé depuis un réseau fiable et vérifiez l’empreinte de l’hôte avant de continuer. Arrêtez-vous immédiatement si elle ne correspond pas aux informations de livraison.

  3. 03
    Remplacer les identifiants temporaires

    Ajoutez votre clé publique SSH au fichier d’autorisation. Vérifiez qu’une nouvelle session fonctionne, puis supprimez les accès temporaires devenus inutiles.

  4. 04
    Fermer correctement la session

    Arrêtez d’abord les tâches au premier plan et vérifiez que les journaux ont été écrits, puis utilisez exit pour quitter. Ne fermez pas directement un terminal qui exécute encore une tâche de publication.

  5. 05
    Vérifier les problèmes d’accès

    En cas de délai d’attente, vérifiez d’abord le réseau et le port ; en cas de refus de connexion, vérifiez l’adresse et l’état du service ; en cas d’échec d’authentification, vérifiez le nom d’utilisateur, les permissions de la clé et le fichier d’autorisation.

Parcours avec interface graphique

Vérification de la connexion VNC

  1. 01
    Préparer le client et l’adresse

    Utilisez un client VNC fiable et renseignez l’adresse et le port du nœud selon les informations de livraison. Désactivez avant la connexion la mémorisation inutile des identifiants dans le client.

  2. 02
    Effectuer la première vérification de l’écran

    Vérifiez que l’interface graphique macOS attendue s’affiche et contrôlez la région ainsi que la configuration de l’appareil. Si l’affichage est anormal, n’importez pas immédiatement de code ou de certificats.

  3. 03
    Mettre à jour les identifiants d’accès

    Remplacez le mot de passe temporaire, reconnectez-vous et vérifiez que les nouveaux identifiants fonctionnent. Ne stockez pas les identifiants complets dans les discussions d’équipe ou les scripts de build.

  4. 04
    Quitter les sessions inactives

    Enregistrez votre travail, fermez les fenêtres sensibles et quittez la session. En cas de collaboration, notez l’utilisateur actuel et les tâches graphiques en cours.

  5. 05
    Diagnostiquer les anomalies d’affichage

    En cas d’écran noir, reconnectez-vous et vérifiez l’état de la session ; en cas de lenteur, réduisez la qualité d’affichage ; si la connexion est impossible, revenez aux vérifications de l’adresse, du port et du réseau local.

Journal de diagnostic de connexion

Comprendre les journaux SSH détaillés plutôt que réessayer en boucle

Le mode détaillé indique si la connexion bloque au stade du réseau, de l’empreinte ou de l’authentification. L’adresse ci-dessous est fournie à titre d’exemple ; utilisez les informations de livraison de la commande pour la connexion réelle.

support-check · ssh diagnostic 
$ ssh -v -p 22 build@203.0.113.24
OpenSSH: reading configuration data
debug1: Connecting to 203.0.113.24 port 22
debug1: Connection established
debug1: identity file ~/.ssh/id_ed25519 type 3

The authenticity of host cannot be established.
ED25519 key fingerprint is SHA256:verify-with-delivery-record
Continue connecting only after fingerprint verification.

debug1: Server host key accepted
debug1: Offering public key: ~/.ssh/id_ed25519
debug1: Authentication succeeded (publickey)
Connected to the dedicated physical Mac node

$ sw_vers
ProductName: macOS

$ exit
Connection closed.
TIMEOUT

Bloqué longtemps sur Connecting

Passez d’abord à un réseau dont le bon fonctionnement est confirmé, puis vérifiez l’adresse et le port. Si plusieurs réseaux expirent, notez l’heure, l’environnement de sortie local et les journaux complets.

FINGERPRINT

L’empreinte de l’hôte ne correspond pas aux informations enregistrées

Arrêtez la connexion ; ne supprimez pas directement l’enregistrement de l’hôte connu localement pour réessayer. Vérifiez d’abord le nœud de la commande et les informations de livraison, puis confirmez la cause du changement via un ticket.

AUTH

Le réseau fonctionne, mais l’authentification échoue

Vérifiez le nom d’utilisateur, le chemin de la clé privée, les permissions du fichier et l’intégrité de la clé publique dans le fichier d’autorisation. Dans les journaux transmis, masquez le contenu des clés et conservez uniquement les informations de la phase d’authentification.

Chaîne d’outils de développement

Fixez d’abord la sélection de Xcode, puis traitez les erreurs du projet

Les dérives d’environnement les plus courantes sur une machine de build concernent le chemin des outils en ligne de commande, les noms de cibles, l’état des dépendances et les variables de signature. Vérifiez d’abord la machine, puis le projet.

XCODE

Confirmer la sélection des outils en ligne de commande

Exécutez xcode-select -p pour afficher le chemin actuel, puis utilisez xcodebuild -version pour vérifier la version. Après avoir changé de version, rouvrez le terminal afin que les tâches suivantes utilisent un environnement cohérent.

Attendu : chemin et version concordants
TARGET

Lister les cibles réellement disponibles

Exécutez d’abord xcodebuild -listpour confirmer les noms du workspace, du project, du scheme et de la configuration, puis inscrivez les noms exacts dans la commande d’automatisation.

Attendu : les cibles sont énumérables
SIGNING

Séparer les variables de signature de la configuration du projet

Vérifiez que les variables nécessaires au build existent dans la session actuelle et évitez d’écrire des valeurs sensibles dans le dépôt. Affichez uniquement leur présence, sans révéler leur contenu complet dans les journaux.

Attendu : variables présentes et non divulguées
LOGS

Archiver les journaux complets du build

Pour chaque tâche, conservez la commande, l’heure de début, le code de sortie, les journaux de build et le chemin des artefacts. En cas d’échec, gardez aussi le contexte autour de la première erreur, pas seulement le résumé final.

Attendu : échec reproductible
Build automatisé

Rendre le self-hosted runner identifiable, isolé et désinscriptible

L’objectif de l’intégration d’un runner n’est pas seulement de réussir la première tâche : les tâches suivantes doivent savoir sur quel nœud et dans quel répertoire s’exécuter, et les relations d’enregistrement doivent être nettoyées lors de la désactivation.

  1. 01

    Vérifier l’identité d’exécution avant l’enregistrement

    Créez une identité d’exécution et un répertoire de travail dédiés. Vérifiez que cette identité peut lire le dépôt et écrire dans le répertoire de build, sans disposer par défaut de droits d’administration sans rapport avec le build.

    Vérification : une tâche manuelle s’exécute avec la même identité
  2. 02

    Décrire les capacités réelles avec des labels

    Les labels doivent décrire la région, la famille de puces, la version principale de Xcode et l’usage. Évitez « dernier » ou « plus rapide », qui deviennent inexacts avec le temps.

    Vérification : les conditions de planification correspondent à un seul nœud cible
  3. 03

    Isoler les répertoires de travail

    Utilisez des sous-répertoires distincts pour les dépôts ou pipelines différents et gérez les caches séparément. À la fin de la tâche, supprimez les fichiers temporaires, mais conservez les caches clairement issus d’une source et encore utiles.

    Vérification : les deux tâches ne se remplacent pas mutuellement leurs artefacts
  4. 04

    Limiter la concurrence et les conflits de ressources

    Commencez par une seule tâche, observez le CPU, la mémoire, le disque et la durée du build, puis décidez s’il faut augmenter la concurrence. Les tâches graphiques et les builds lourds ne doivent pas s’exécuter simultanément sans suivi.

    Vérification : aucun accroissement continu de l’espace d’échange pendant les pics
  5. 05

    Désinscrire complètement le runner lors de sa désactivation

    Arrêtez d’abord l’acceptation de nouvelles tâches, attendez la fin des tâches en cours, puis désinscrivez le runner de la plateforme d’automatisation et supprimez le jeton d’enregistrement ainsi que le répertoire de travail devenu inutile.

    Vérification : les anciens labels n’acceptent plus de tâches
Ne confiez pas le même répertoire de travail à plusieurs tâches concurrentes. Les caches de dépendances, DerivedData, les archives et les fichiers de signature temporaires peuvent se remplacer mutuellement et provoquer des échecs de build apparemment aléatoires.
Terminologie

Huit termes à harmoniser en priorité

Utiliser les mêmes termes dans les tickets et la documentation d’équipe évite de confondre réseau, appareil, session et outils de build.

Nœud physique
Équipement matériel qui exécute réellement macOS. Une commande BookaMac correspond à un Mac mini physique, et non à une instance de calcul partagée abstraite.
Dédié
Pendant la durée de location, l’appareil est attribué à un seul client et la machine physique n’est pas partagée avec les charges de travail d’autres clients.
Mac cloud
Mac situé sur un nœud distant et accessible par réseau. Le terme décrit l’emplacement et le mode d’accès, pas une machine virtuelle.
VNC
Mode de connexion permettant d’afficher et de contrôler à distance l’interface graphique macOS, adapté aux tâches nécessitant fenêtres, affichage et interactions.
SSH
Connexion chiffrée en ligne de commande, adaptée à l’exécution de scripts, au transfert de fichiers, à la gestion des builds et à la collecte de journaux de diagnostic.
self-hosted runner
Exécuteur de tâches automatisées enregistré et administré par l’équipe, dont les tâches s’exécutent sur le nœud Mac physique dédié désigné.
Cache de build
Données intermédiaires conservées pour réduire les téléchargements et compilations répétitifs. Le cache accélère les tâches, mais peut provoquer une dérive d’environnement après un changement de version.
Fichier de provisioning
Élément de configuration de signature utilisé pour les processus de publication et de test. Gérez-le selon les autorisations du projet et supprimez-le lors d’un transfert ou du retrait de l’environnement.
Arbre de décision par symptôme

Passez du symptôme observé à la prochaine vérification

Développez d’abord le symptôme le plus proche. Après chaque point de contrôle, passez au suivant ; ne sautez pas les étapes intermédiaires sans consigner les résultats.

Impossible de se connecter au nœud : que vérifier en premier ?
  1. Confirmer l’adresse :Recopiez l’adresse de l’hôte, le port et le nom d’utilisateur depuis les informations de livraison de la commande actuelle.
  2. Distinguer délai d’attente et refus :Un délai d’attente indique généralement un problème de réseau local ou de liaison ; un refus immédiat concerne plutôt l’adresse, le port ou le mode de connexion.
  3. Activer les journaux détaillés :Utilisez ssh -v pour déterminer si la connexion réseau est établie, si la vérification de l’empreinte est passée et à quelle étape l’authentification s’arrête.
  4. Tester depuis un autre réseau fiable :Si le résultat change, consignez les deux environnements réseau au lieu d’indiquer seulement « la connexion fonctionne parfois ».
  5. Contacter l’assistance :Si plusieurs réseaux échouent, joignez l’identifiant de commande, la région, l’heure et les journaux détaillés expurgés au ticket.
Échec du build : problème de Xcode, du projet ou des dépendances ?
  1. Fixer la version :Consignez la sortie de xcode-select -p et de xcodebuild -version .
  2. Lister les cibles :Vérifiez que les noms du scheme, de la configuration, du workspace ou du project existent réellement.
  3. Trouver la première erreur :Repérez dans les journaux la première erreur explicite ; ne déduisez pas la cause à partir du résumé final de l’échec.
  4. Vérifier les dépendances :Sans modifier les fichiers du projet, résolvez à nouveau les dépendances selon le fichier de verrouillage et comparez les résultats.
  5. Réduire le périmètre :Construisez séparément la cible minimale afin de déterminer si l’échec concerne l’environnement, la configuration du projet ou un module particulier.
Espace disque insuffisant : quels répertoires vérifier en priorité ?
  1. Confirmer l’utilisation globale :Utilisez df -h pour consulter l’espace au niveau du volume, plutôt que le seul répertoire d’un projet.
  2. Localiser les grands répertoires :Vérifiez DerivedData, les archives, les données des simulateurs, les caches de dépendances et le répertoire de travail du runner.
  3. Distinguer cache et artefacts :Le cache peut être reconstruit ; archivez d’abord les artefacts livrables et les journaux de diagnostic avant de les supprimer.
  4. Arrêter les tâches actives :Avant le nettoyage, vérifiez qu’aucun build n’écrit dans le répertoire cible afin d’éviter un état intermédiaire corrompu.
  5. Réexaminer la source de la croissance :Après le nettoyage, observez l’espace ajouté par la tâche suivante afin d’identifier le véritable répertoire qui continue de croître.
Certificat ou fichier de provisioning défaillant : comment éviter une réinstallation à l’aveugle ?
  1. Consigner le message d’erreur original :Distinguez l’élément introuvable, expiré, insuffisamment autorisé ou incompatible avec la configuration.
  2. Vérifier la cible de build :Confirmez que le scheme, la configuration et les paramètres de signature actuels correspondent au projet attendu.
  3. Vérifier les autorisations du trousseau :Vérifiez que l’identité exécutant le build peut accéder aux éléments requis, sans élargir les autorisations inutiles.
  4. Vérifier le fichier de provisioning :Confirmez que le fichier correspond aux exigences de la tâche actuelle et évitez de conserver plusieurs anciennes versions difficiles à distinguer.
  5. Protéger les éléments sensibles :Dans le ticket, transmettez uniquement l’erreur, les noms et les métadonnées nécessaires ; n’envoyez ni clé privée ni identifiants complets.
La vitesse de connexion ou de build fluctue : comment localiser le problème ?
  1. Indiquer une plage horaire :Notez le début, la fin et le caractère continu ou non du problème ; « c’est lent récemment » ne suffit pas comme seule description.
  2. Mesurer séparément :Observez séparément l’affichage distant, le transfert de fichiers, le téléchargement des dépendances et le build local ; ne les réduisez pas à une seule conclusion de vitesse.
  3. Vérifier les tâches concurrentes :Vérifiez si d’autres builds, indexations, transcodages ou tâches de modèle utilisent simultanément les ressources.
  4. Comparer les réseaux :Répétez la même action sur différents réseaux fiables afin de distinguer la liaison locale de la charge des tâches distantes.
  5. Conserver un échantillon :Soumettez la région, l’heure, la durée des commandes et les journaux expurgés afin de permettre une vérification dans les mêmes conditions.
Parcours de contact avec l’assistance

Que doit contenir un ticket prêt pour le diagnostic ?

Commencez par rassembler les faits, puis envoyez-les via la console. Un contexte complet permet généralement de localiser plus vite le problème que plusieurs captures ajoutées séparément.

01

Identifiant de commande

Fournissez uniquement l’identifiant de commande nécessaire ; n’envoyez pas de justificatifs de paiement ni d’informations sans rapport.

02

Région du nœud

Indiquez Singapour, Japon (Tokyo), Corée du Sud (Séoul) ou Hong Kong, ainsi que le mode de connexion utilisé.

03

Heure de l’incident

Précisez le fuseau horaire, l’heure de la première apparition, la durée et la possibilité de reproduire régulièrement le problème.

04

Journaux expurgés

Conservez les commandes, codes de sortie et contextes d’erreur ; masquez les jetons, mots de passe, clés privées et identifiants complets.

Reproduisez d’abord le problème avec la documentation, puis joignez les preuves au ticket

La console permet de consulter les commandes existantes et d’envoyer des tickets techniques. Si vous comparez encore les configurations, examinez d’abord les spécifications et les workflows adaptés des deux offres de Mac mini physiques dédiés.

Accéder à la console Comparer les configurations