Doku

Runner in 10 Minuten registrieren

Ihre MacRun-Maschine ist ein normaler self-hosted GitHub Actions Runner. Sie behalten Ihre Pipeline und ändern zwei Zeilen YAML.

01

Mit Ihrer Maschine verbinden

Ihre Maschine hängt in einem privaten Tailscale-Netzwerk statt im öffentlichen Internet. Es gibt also keinen offenen SSH-Port, den jemand finden könnte, und nichts abzusichern. Für den Zugang brauchen Sie zwei Dinge, und das nur einmal.

Installieren Sie Tailscale von tailscale.com/download und melden Sie sich an. Für den privaten Gebrauch und für die Kontogrößen, die die meisten Teams hier brauchen, ist es kostenlos. Es läuft unter macOS, Linux und Windows. Nehmen Sie dann die Freigabe-Einladung an, die wir schicken, sobald Ihre Maschine bereit ist. Sie gibt Ihnen Zugriff auf genau diese eine Maschine und auf nichts anderes in unserem Netzwerk.

Ihr Portal zeigt den genauen Befehl, mit der Adresse Ihrer Maschine schon eingesetzt:

ssh runner@100.x.x.x

Es gibt kein Passwort und keinen Schlüssel zu verwalten. Die Authentifizierung übernimmt Tailscale. Nutzt Ihr Tailscale-Konto eine andere E-Mail-Adresse als Ihre Rechnungsadresse, fordern Sie in Ihrem Portal eine Freigabe dafür an.

Ihre CI-Jobs brauchen kein Tailscale. GitHub Actions erreicht den Runner über die eigene ausgehende Verbindung von GitHub. Tailscale brauchen Sie also nur, wenn Sie eine Shell auf der Maschine wollen.

02

Den Bildschirm öffnen, wenn Sie ihn brauchen

Für CI reicht SSH. Wenn ein Log einmal nicht genügt, erreichen Sie dieselbe Maschine per Bildschirmfreigabe über dasselbe private Netzwerk. Instruments, der Simulator und die Oberfläche von Xcode funktionieren dann wie lokal. Ihr Portal zeigt die Adresse, den Benutzer runner und ein Passwort, das nur für Ihre Miete gilt.

Auf einem Mac öffnen Sie den Finder, dann Gehe zu → Mit Server verbinden (⌘K):

vnc://100.x.x.x

Unter Windows installieren Sie RealVNC Viewer oder TightVNC und verbinden sich mit 100.x.x.x:5900. Unter Linux funktionieren Remmina und TigerVNC, mit derselben Adresse. Fragt Ihr Client nur nach einem Passwort, lassen Sie den Benutzernamen leer.

Kopieren und Einfügen. Viewer unter Windows und Linux können die Zwischenablage nicht mit dem Mac teilen, denn die macOS-Bildschirmfreigabe ignoriert sie. Apples Bildschirmfreigabe-App auf einem Mac teilt sie dagegen. Unter Windows übertragen Sie Text stattdessen per SSH. Fügen Sie diese Zeilen in PowerShell ein:

# 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"

Die erste Zeile lässt PowerShell UTF-8 senden und lesen. So kommen Umlaute und andere Sprachen korrekt an. Oder Sie nutzen unser kleines Skript macrun-clip.ps1. Starten Sie es mit push, pull oder sync und Ihrer Adresse. Sync überträgt Änderungen in beide Richtungen, bis Sie Strg+C drücken. Es überträgt nur Text. Unter Linux leiten Sie dieselben ssh-Befehle durch xclip oder wl-copy.

Genau das können die meisten CI-Dienste nicht. Ein gehosteter Runner gibt Ihnen Logs und sonst nichts. Ein Absturz, der nur unter Instruments auftritt, lässt sich dort also nicht untersuchen.

03

Registrierungstoken von GitHub holen

Gehen Sie in Ihrem Repository (oder Ihrer Organisation) zu Settings → Actions → Runners → New runner. GitHub zeigt ein einmaliges Token an. Sie fügen es gleich in den Befehl unten ein. Runner auf Organisationsebene teilen sich alle Repositorys der Organisation.

04

Runner auf Ihrer Maschine registrieren

Verbinden Sie sich wie oben per SSH. Führen Sie dann den Konfigurationsbefehl aus Ihrem Portal aus (er enthält schon das Label Ihres Geräts):

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

Der Daemon runner-agent hält diesen Dienst automatisch am Leben. Stürzt er ab, wird er innerhalb von 30 Sekunden neu gestartet.

05

Zwei Zeilen YAML ändern

Richten Sie Ihren Workflow auf den Runner aus. Das ist schon der ganze Diff:

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

Alles andere in Ihrer Pipeline bleibt genau so, wie es ist.

06

Xcode-Versionen

Aktuelle Xcode-Versionen sind unter /Applications vorinstalliert. Um eine für einen Job auszuwählen, setzen Sie DEVELOPER_DIR. Dafür ist kein sudo nötig. Sie können auch in Ihrem Portal eine neue Version anfordern (meist noch am selben Tag):

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

Die Caches sind schon warm

Weil die Maschine Ihnen gehört, bleiben die Caches zwischen den Läufen auf der lokalen Platte. Es fällt also kein erneuter Download an. Übliche Pfade:

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

Sie können weiterhin actions/cache nutzen, wenn Sie deterministische Restore-Keys wollen. Für die meisten iOS-Builds bringt aber die warme lokale Platte den Vorteil.

08

Ihre Maschine verwalten

Neustarts, Xcode-Versionen und die Abrechnung verwalten Sie in Ihrem Portal. Brauchen Sie etwas anderes? Antworten Sie auf eine beliebige MacRun-E-Mail, und ein Mensch antwortet Ihnen.