Docs

Enregistrez votre runner en 10 minutes

Votre machine MacRun est un runner GitHub Actions self-hosted standard. Gardez votre pipeline et modifiez deux lignes de YAML.

01

Se connecter à la machine

Votre machine se trouve sur un réseau Tailscale privé, pas sur l’internet public. Il n’y a donc aucun port SSH ouvert à trouver, et rien à durcir. Pour y accéder, il faut deux choses, une seule fois.

Installez Tailscale depuis tailscale.com/download et connectez-vous. C’est gratuit pour un usage personnel et pour la taille de compte dont la plupart des équipes ont besoin ici. Tailscale tourne sous macOS, Linux et Windows. Ensuite, acceptez l’invitation de partage que nous envoyons quand votre machine est prête. Elle vous donne accès à cette machine, et à rien d’autre sur notre réseau.

Votre portail affiche la commande exacte, avec l’adresse de votre machine déjà remplie :

ssh runner@100.x.x.x

Aucun mot de passe ni aucune clé à gérer : Tailscale s’occupe de l’authentification. Votre compte Tailscale utilise un autre e-mail que votre adresse de facturation ? Demandez un partage pour cet e-mail dans votre portail.

Vos jobs de CI n’ont pas besoin de Tailscale. GitHub Actions atteint le runner par la propre connexion sortante de GitHub. Tailscale ne sert donc que lorsque vous voulez un shell sur la machine.

02

Ouvrir l’écran, quand vous en avez besoin

SSH suffit pour la CI. Quand un log ne suffit pas, la même machine est accessible en partage d’écran, sur le même réseau privé. Instruments, le Simulator et l’interface de Xcode fonctionnent alors comme en local. Votre portail affiche l’adresse, l’utilisateur runner et un mot de passe propre à votre location.

Sur un Mac, ouvrez le Finder, puis Aller → Se connecter au serveur (⌘K) :

vnc://100.x.x.x

Sur Windows, installez RealVNC Viewer ou TightVNC et connectez-vous à 100.x.x.x:5900. Sur Linux, Remmina et TigerVNC fonctionnent tous les deux, avec la même adresse. Si votre client ne demande qu’un mot de passe, laissez le nom d’utilisateur vide.

Copier-coller. Les visionneuses Windows et Linux ne peuvent pas partager le presse-papiers avec le Mac, car le partage d’écran de macOS ignore le leur. L’app Partage d’écran d’Apple sur un Mac le partage, elle. Depuis Windows, faites passer le texte par SSH. Collez ces lignes dans PowerShell :

# Once per window: send and read text as UTF-8
$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)

# Mac to PC
ssh runner@100.x.x.x "LANG=en_US.UTF-8 pbpaste" | Set-Clipboard

# PC to Mac
Get-Clipboard -Raw | ssh runner@100.x.x.x "LANG=en_US.UTF-8 pbcopy"

La première ligne fait envoyer et lire l’UTF-8 à PowerShell. Les accents et les autres langues arrivent ainsi intacts. Vous pouvez aussi utiliser notre petit script macrun-clip.ps1. Lancez-le avec push, pull ou sync et votre adresse. Sync copie les changements dans les deux sens jusqu’à ce que vous appuyiez sur Ctrl+C. Il ne déplace que du texte. Sur Linux, faites passer les mêmes commandes ssh par xclip ou wl-copy.

C’est ce que la plupart des services de CI ne savent pas faire. Un runner hébergé vous donne des logs et rien d’autre. Un crash qui ne se reproduit que sous Instruments est alors un crash impossible à analyser.

03

Obtenir un token d’enregistrement auprès de GitHub

Dans votre dépôt (ou votre organisation), allez dans Settings → Actions → Runners → New runner. GitHub affiche un token à usage unique. Vous le collerez dans la commande ci-dessous. Les runners au niveau de l’organisation sont partagés entre tous ses dépôts.

04

Enregistrer le runner sur votre machine

Connectez-vous en SSH comme ci-dessus, puis lancez la commande de configuration de votre portail (elle remplit déjà le label de votre machine) :

cd ~/actions-runner
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO \
  --token <RUNNER_TOKEN> \
  --labels self-hosted,macOS,macrun-unit-01 \
  --unattended

# start it as a service (survives reboots)
./svc.sh install && ./svc.sh start

Le démon runner-agent maintient automatiquement ce service en vie. En cas de crash, il est relancé en moins de 30 secondes.

05

Modifier deux lignes de YAML

Faites pointer votre workflow vers le runner. Voici tout le diff :

 jobs:
   build:
-    runs-on: macos-latest
+    runs-on: [self-hosted, macOS, macrun-unit-01]

Tout le reste de votre pipeline reste exactement identique.

06

Versions de Xcode

Les versions récentes de Xcode sont préinstallées dans /Applications. Pour en choisir une dans un job, définissez DEVELOPER_DIR. Aucun sudo n’est nécessaire. Vous pouvez aussi demander une nouvelle version depuis votre portail (en général le jour même) :

jobs:
  build:
    env:
      DEVELOPER_DIR: /Applications/Xcode.app/Contents/Developer
    steps:
      - run: ls -d /Applications/Xcode*.app   # installed versions
      - run: xcodebuild -version
07

Les caches sont déjà chauds

Comme la machine est à vous, les caches restent sur le disque local entre deux exécutions. Vous ne payez donc pas le prix d’un nouveau téléchargement. Chemins courants :

~/Library/Developer/Xcode/DerivedData   # build cache
~/Library/Caches/CocoaPods              # pods
~/.gradle  ~/.npm  ~/.gem               # toolchain caches
~/Library/Caches/org.swift.swiftpm      # SwiftPM

Vous pouvez toujours utiliser actions/cache si vous voulez des clés de restauration déterministes. Mais pour la plupart des builds iOS, c’est le disque local chaud qui fait la différence.

08

Gérer votre machine

Redémarrez, demandez des versions de Xcode et gérez la facturation depuis votre portail. Besoin d’autre chose ? Répondez à n’importe quel e-mail de MacRun et un humain vous répond.