Dieser Beitrag richtet sich an Plattformverantwortliche, die iOS- oder macOS-Builds in TeamCity ergänzen und einen TeamCity 2026.1 macOS Build Agent zuverlässig betreiben müssen.

Er ist ebenso relevant, wenn Sie lokale Mac-mini-Systeme zu gemeinsamen Build-Knoten machen oder mehrere Remote-Macs mit Signaturisolierung, Kapazitätsnachweisen und Wiederherstellung planen.

Letztes Update: 30.08.2026. Die versionsbezogenen Aussagen wurden anhand der offiziellen TeamCity-Dokumentation für On-Premises 2026.1 und der ergänzenden Cloud-Dokumentation für 2026.2 sowie der Xcode-Dokumentation abgeglichen.

Java 21 ist die erste harte Schranke

Für TeamCity On-Premises 2026.1 ist Java 21 für die Agent-Laufzeit die maßgebliche Baseline. Ein vorhandenes älteres JDK kann dazu führen, dass der Agent bereits vor der Registrierung nicht korrekt startet. Prüfen Sie deshalb nicht nur, ob Java auf dem Mac installiert ist, sondern welche Java-Laufzeit der Agent-Prozess tatsächlich verwendet. Die offiziellen Systemanforderungen für TeamCity sind dabei die Referenz für die Version 2026.1.

java -version
echo "$JAVA_HOME"

Diese Prüfung beantwortet jedoch nur die Laufzeitfrage. Das JDK, mit dem der TeamCity-Agent selbst ausgeführt wird, ist nicht automatisch das JDK, das Ihr Projekt beim Kompilieren verwendet. Eine Pipeline kann beispielsweise eine eigene Toolchain oder eine projektbezogene Java-Konfiguration aufrufen. Dokumentieren Sie beide Werte getrennt:

• Agent-JDK: Startet und verbindet den TeamCity-Agent.
• Projekt-JDK: Wird von Build-Skripten, Gradle oder weiteren Werkzeugen verwendet.
• Xcode-Toolchain: Wird für Apple-Plattformen über Xcode und die zugehörigen Kommandozeilenwerkzeuge angesprochen.

Vermischen Sie diese Ebenen nicht. Ein korrekt gestarteter Agent kann dennoch eine fehlerhafte Projektumgebung besitzen.

Hostdaten statt Annahmen

Erfassen Sie vor der Registrierung mindestens den Mac-Typ, die Chipfamilie, die macOS-Version, den verfügbaren Speicherplatz, den Installationspfad von Xcode und den Dienstbenutzer. Bei Apple Silicon sollte außerdem geklärt sein, ob sämtliche Build-Werkzeuge nativ oder über eine Kompatibilitätsschicht laufen. Das ist keine kosmetische Information: Unterschiedliche Toolchains können sich bei Skripten, Simulatoren und signierten Artefakten unterschiedlich verhalten.

Der produktive Prozess sollte unter einem eigenen Nicht-Root-Konto laufen. Administratorrechte sind für die anfängliche Installation, Systemdienste, bestimmte Verzeichnisrechte und die Einrichtung von launchd erforderlich. Der laufende Agent sollte diese Rechte aber nicht dauerhaft behalten. So begrenzen Sie den Schaden, falls ein Build-Skript kompromittiert wird oder ein nicht vertrauenswürdiger Pull Request auf dem Knoten landet.

Ein Hostname allein ist kein Sicherheits- oder Routingmerkmal. Verwenden Sie einen festen Agent-Namen, der den Zweck des Knotens beschreibt, und hinterlegen Sie die zugehörigen Parameter kontrolliert. Die TeamCity-Anleitung zur Agent-Konfiguration beschreibt die relevanten Konfigurationsfelder und die Registrierung.

„Connected“ ist kein Produktionsnachweis

Ein Agent kann im Server-Dashboard als verbunden erscheinen und trotzdem keine geeigneten Builds erhalten. Drei getrennte Ebenen müssen geprüft werden:

1. Der Prozess läuft mit der erwarteten Java-Laufzeit.
2. Der Agent registriert sich unter dem richtigen Namen und mit gültiger Autorisierung.
3. Die Build-Konfiguration darf den Agent aufgrund von Pool, Anforderungen und Parametern tatsächlich auswählen.

Notieren Sie den verwendeten serverUrl, den Autorisierungstoken, den Agent-Namen und den Zeitpunkt der Registrierung. Das Token gehört nicht in ein öffentliches Repository und nicht in frei lesbare Shell-Historien. Bewahren Sie die Agent-Konfigurationsdatei mit restriktiven Dateirechten auf.

TeamCity verwendet für den Agent-Betrieb ein Modell, bei dem der Agent die Verbindung zum Server aufbaut. Das ist für ausgehende Netzwerkregeln wichtig: Ein Unternehmen muss nicht zwingend eingehende Verbindungen bis zum Mac öffnen, muss aber die ausgehende Verbindung zum TeamCity-Server und gegebenenfalls zum Reverse Proxy erlauben. Bei HTTPS sollten Zertifikatskette, Hostname und Proxy-Regeln gemeinsam geprüft werden. Ein TCP-Test allein beweist keine funktionierende TeamCity-Registrierung.

Autorisierung und Reverse Proxy

Wenn ein Reverse Proxy vor dem TeamCity-Server liegt, prüfen Sie nicht nur den Browserzugriff. Kontrollieren Sie die Agent-Logs auf falsche Pfade, TLS-Fehler, Weiterleitungen und abgebrochene Verbindungen. Ein Dashboard mit einem alten Verbindungsstatus kann einen Fehler verdecken, wenn der Prozess zwar läuft, aber keine neuen Serveranfragen verarbeitet.

Die schnellste belastbare Prüfung besteht aus einem kleinen, absichtlich dokumentierten Ablauf:

1. Agent-Prozess beenden.
2. Prozess unter dem vorgesehenen Dienstbenutzer starten.
3. Logdatei während der Verbindung beobachten.
4. Autorisierung im TeamCity-Server bestätigen.
5. Einen Test-Build ausschließlich diesem Agent Pool zuweisen.
6. Nach Abschluss prüfen, ob der Agent wieder verfügbar und der Arbeitsbereich sauber ist.

TeamCity Cloud 2026.2 kann für Installations- und Startmechanismen als zusätzliche Referenz dienen. Die dort beschriebenen Cloud-Agent-Abläufe dürfen jedoch nicht automatisch als Beleg für identische Funktionen in TeamCity On-Premises 2026.1 verwendet werden. Diese Trennung ist bei einer internen Betriebsdokumentation wichtig.

Vollständiges Xcode statt nur Command Line Tools

Für iOS- und macOS-Builds genügt es nicht, dass xcodebuild irgendeine Ausgabe liefert. Auf dem Knoten muss die für das Projekt erforderliche vollständige Xcode-Installation vorhanden sein. Die Command Line Tools sind ein eigener Bestandteil und ersetzen nicht automatisch die vollständige Entwicklungsumgebung. Die offizielle Referenz zu den Xcode Command Line Tools hilft bei der Abgrenzung.

Prüfen Sie den aktiven Pfad und die tatsächlich verwendete Version:

xcode-select -p
xcodebuild -version

Die Ausgabe muss mit der TeamCity-Konfiguration und dem Projektziel übereinstimmen. Eine bloße Installation auf dem Datenträger reicht nicht, wenn xcode-select auf eine andere Version zeigt.

Drei Ebenen der Zuordnung

Bei einem einzelnen Xcode-Stand genügt oft ein definierter Pfad zur Xcode-Installation. Bei mehreren Versionen müssen Sie drei Ebenen synchron halten:

• Build-Anforderung: Welche Xcode-Version oder welches SDK verlangt das Projekt?
• Agent Parameter: Welche Xcode-Version meldet der konkrete Mac?
• Agent Requirement: Welche Agenten dürfen diesen Build ausführen?

TeamCity dokumentiert die Xcode-Projektintegration und die verfügbaren Build-Parameter in den Xcode-Build-Hinweisen sowie bei den vordefinierten Build-Parametern. Für Ihre Abnahme zählt aber nicht die Existenz eines Parameters, sondern die Übereinstimmung mit der realen Werkzeugausgabe auf dem Host.

Ein typischer Fehler sieht so aus: Der Agent meldet sich korrekt an, besitzt ein Xcode-bezogenes Parameterfeld, wird aber wegen einer unpräzisen Anforderung für einen Build ausgewählt, dessen SDK nicht installiert ist. Das Ergebnis ist ein später Fehler im Build statt einer sauberen Ablehnung bei der Agent-Auswahl.

Achtung: Ein „online“ angezeigter TeamCity-Agent ist nur ein Kommunikationsstatus. Für Xcode-Aufgaben müssen Sie zusätzlich Pfad, Version, SDK, Architektur und Signaturumgebung aus dem Build-Log nachweisen.

Gemeinsame Agents sind keine automatische Sicherheitsgrenze

TeamCity-Builds auf demselben Agent sind nicht automatisch voneinander isoliert. Arbeitsdateien, Caches, Umgebungsvariablen und temporäre Artefakte können nach einem Build sichtbar bleiben, wenn die Pipeline sie nicht ausdrücklich entfernt. Besonders kritisch ist das bei Signaturmaterial, Provisioning-Dateien und exportierten Archiven.

Ordnen Sie Aufgaben deshalb nach Vertrauensniveau:

• Nicht vertrauenswürdige Pull Requests gehören in einen separaten Pool.
• Normale Tests können einen gemeinsamen Test-Agent verwenden, wenn die Bereinigung nachweisbar ist.
• Release-Builds mit Signaturzugriff sollten auf dedizierten Macs oder einem strikt getrennten Agent Pool laufen.
• Produktionsschlüssel dürfen nicht dauerhaft im allgemeinen Benutzer-Keychain liegen.

Prüfen Sie den Checkout-Pfad, die Clean-Checkout-Regel und die Cache-Verzeichnisse. Ein sauberer Arbeitsbereich ist nicht nur eine Frage reproduzierbarer Builds, sondern auch eine Maßnahme gegen Daten- und Credential-Reste.

Für die Signaturisolierung empfiehlt sich ein temporäres Keychain mit kontrolliertem Entsperrvorgang. Nach dem Build müssen Sie es schließen, entfernen und im Log dokumentieren. Kontrollieren Sie anschließend die Schlüsselauflistung und suchen Sie im Arbeitsbereich nach Provisioning-Dateien, Zertifikaten und exportierten Signaturartefakten.

Weitere Einzelheiten zur Trennung von TeamCity Agent Pools sollten Sie in Ihre Betriebsrichtlinie übernehmen. Die Pool-Zuordnung ersetzt allerdings keine Berechtigungsprüfung innerhalb des Mac-Systems.

Konfigurationsvergleich für die Entscheidung

Ein dedizierter Mac ist nicht in jedem Fall erforderlich. Sobald jedoch externe Beiträge, Kundencode, Produktionszertifikate oder regulatorische Anforderungen zusammentreffen, ist ein gemeinsamer Release-Agent schwerer zu rechtfertigen.

Automatischer Start mit launchd

Ein Mac-Agent, der erst nach einer grafischen Anmeldung startet, ist für unbeaufsichtigte Builds riskant. Richten Sie den Startmechanismus unter dem vorgesehenen Benutzer ein und prüfen Sie Eigentümer, absolute Pfade, Umgebungsvariablen und Logverzeichnis. Die offizielle Dokumentation zum Agent-Start dient als Referenz für Startparameter. Übertragen Sie Cloud-Abläufe aber nicht ungeprüft auf On-Premises 2026.1.

Entscheidungshilfe: Produktionsknoten oder Pilot?

• Wenn Java 21, Xcode-Pfad und Agent-Registrierung dokumentiert sind, wählen Sie den Knoten für einen isolierten Pilot-Pool.
• Wenn die Xcode-Version nur über eine manuelle Benutzeranmeldung funktioniert, fallen Sie zurück auf einen nicht produktiven Testknoten.
• Wenn Signaturdaten nach dem Build nicht nachweisbar entfernt werden, wählen Sie einen dedizierten Mac mit überarbeiteter Bereinigung.
• Wenn ein Neustart ohne interaktive Anmeldung keine Verbindung und keinen Xcode-Test ermöglicht, verschieben Sie die Produktionsfreigabe.
• Wenn reale PR-, Simulator-, Archivierungs- und Signatur-Builds erfolgreich sind und ein Ersatzknoten übernehmen kann, können Sie den Agent in den Release-Pool aufnehmen.
• Wenn die Warteschlange regelmäßig wächst oder ein einzelner Ausfall den Release blockiert, planen Sie einen zweiten Knoten statt nur die bestehende Maschine größer zu dimensionieren.

Neustartkette statt Einzeltest

Ein remote erreichbarer Mac hat nur dann Produktionswert, wenn er nach einem Neustart selbstständig zurückkehrt. Testen Sie die gesamte Kette:

1. Agent-Dienst unter dem vorgesehenen Benutzer stoppen.
2. Den Mac kontrolliert neu starten.
3. Prüfen, ob launchd den Agent-Prozess wieder aufruft.
4. Verbindung und Autorisierung im TeamCity-Server kontrollieren.
5. Einen Xcode-Befehl ohne grafische Benutzeraktion ausführen.
6. Einen kleinen signaturfreien Test-Build starten.
7. Danach Keychain, Arbeitsbereich und Logs prüfen.

Bewahren Sie für jeden Schritt Zeitstempel und Logauszüge auf. Ein VNC-Zugriff, mit dem ein Administrator den Prozess manuell startet, ist kein Ersatz für Wiederanlaufautomatisierung. Wenn der offizielle Startablauf eine Benutzeranmeldung voraussetzt, muss die Abweichung zwischen diesem Ablauf und Ihrem Unternehmensziel ausdrücklich dokumentiert werden.

Dateirechte sind ein häufiger Fehlerpunkt. Der Dienstbenutzer muss die Agent-Dateien lesen und ausführen können, darf aber nicht pauschal Schreibrechte auf alle Systempfade erhalten. Prüfen Sie auch, ob automatische Agent-Aktualisierungen nach einem Neustart dieselben Eigentümer und dieselbe Java-Umgebung verwenden.

Ein leerer Beispiel-Build beweist keine ausreichende Kapazität. Verwenden Sie eine repräsentative Pipeline aus Ihrem eigenen Repository. Sie sollte mindestens einen Pull-Request-Build, einen Simulator-Test, eine Archivierung und eine kontrollierte Signaturaufgabe abbilden.

Erfassen Sie dabei:

• Wartezeit bis zur Agent-Zuweisung;
• erfolgreiche und fehlgeschlagene Aufträge;
• tatsächlich verwendete Xcode-Version;
• Arbeitsbereich vor und nach dem Build;
• Verhalten nach einem Neustart;
• Wiederaufnahme oder Übernahme durch einen Ersatzknoten;
• fehlende oder verbliebene Signaturartefakte.

Diese Daten liefern die Grundlage für eine Kapazitätsentscheidung. Ein einzelner Agent kann für einen Pilotbetrieb genügen, wenn die Warteschlange überschaubar bleibt und ein manueller Rückfall akzeptabel ist. Für regelmäßige Releases benötigen Sie dagegen einen dokumentierten Ausweichpfad. Die Auslastung sollte aus Ihren Build- und Wartezeitdaten abgeleitet werden, nicht aus einer pauschalen Hardwareempfehlung.

Falls Sie einen Mac mini selbst beschaffen, sollten Sie Lieferzeit, Ersatzgerät, Vor-Ort-Zugriff, Stromversorgung und Wartungsverantwortung in die TCO-Betrachtung aufnehmen. Eine Übersicht zu Mac-mini-Beschaffung für Unternehmen kann als Vergleichspunkt dienen. Für einen temporären oder geografisch verteilten Pilotknoten ist hingegen ein Remote-Mac oft einfacher in die bestehende TeamCity-Struktur einzubinden.

Ein gemieteter Remote-Mac ist nicht automatisch eine produktive Lösung. Er kann aber eine sinnvolle Zwischenstufe sein, wenn Sie zunächst die echte TeamCity-Integration, das Xcode-Routing, die Signaturbereinigung und die Neustartkette mit einem isolierten Knoten testen möchten.

Prüfen Sie vor der Freigabe:

• Ist die Maschine eindeutig einem Agent Pool zugeordnet?
• Sind Nutzer- und Administrationsrechte getrennt?
• Können Sie die ausgehende Verbindung zum TeamCity-Server kontrollieren?
• Sind Xcode und Command Line Tools passend zur Pipeline installiert?
• Werden Schlüssel und Arbeitsbereiche nach jedem relevanten Build bereinigt?
• Gibt es einen dokumentierten Rückfall auf einen anderen Agent?
• Können Sie die Nachweise für Datenschutz, Zugriffskontrolle und Protokollierung intern ablegen?

Die Vorteile liegen in der flexibleren Bereitstellung und darin, dass Sie keine eigene Hardware reservieren müssen. Nachteile bleiben: Sie sind von Netzwerkpfad, Anbieterprozessen und der vereinbarten Verfügbarkeit abhängig. Für langfristige, dauerhaft hohe Last kann eigene Hardware wirtschaftlich und organisatorisch sinnvoller sein. Für Tests, Migrationen, saisonale Last oder den Aufbau eines zweiten Pools ist die Mietoption häufig leichter reversibel.

Im KVMNODE-Überblick für Remote-Macs können Sie prüfen, ob ein isolierter Mac für diesen Pilotansatz verfügbar ist. Entscheidend ist nicht die Werbeaussage, sondern ob Ihre Abnahmetabelle mit echten Logs und Build-IDs vollständig ausgefüllt werden kann.

Wenn Sie derzeit mit einem gemeinsam genutzten lokalen Mac arbeiten, bleiben meist drei Schwächen: eingeschränkte Nachvollziehbarkeit der Arbeitsbereiche, manuelle Wiederherstellung nach Neustarts und ein einzelner Ausfallpunkt für alle Releases. Bei selbst gekaufter Hardware kommen Beschaffung, Ersatzgerät und laufende Wartung hinzu. Für einen zeitlich begrenzten TeamCity-Pilot oder den Aufbau zusätzlicher Kapazität kann ein über KVMNODE gemieteter Remote-Mac deshalb die bessere operative Wahl sein. Nach bestandener Abnahme erweitern Sie die Kapazität nicht pauschal, sondern anhand von Warteschlangen, Wiederherstellungsnachweisen und der benötigten Redundanz.