Wie wird ein TeamCity-Mac-Build-Agent bereitgestellt? Unternehmensleitfaden 2026

Symptom: Der Mac-Agent ist installiert oder wird als online angezeigt, doch TeamCity plant keinen passenden Build ein.
Schnellster Weg: Prüfen Sie nacheinander Server-Verbindung, Agent-Freigabe, Build-Anforderungen und tatsächlich verwendete Xcode-Werkzeuge; erst ein erfolgreicher repräsentativer Build gilt als Abnahme.

Dieser Leitfaden richtet sich an IT-Verantwortliche, die macOS-Buildkapazität planen und einen Mac in die bestehende CI-Umgebung aufnehmen.
TeamCity-Administratoren erhalten Prüfschritte für Agent-Konfiguration, Freigabe und Aufgabenzuordnung.
Plattformingenieure können damit Xcode-Ausführung und Startverhalten unter den tatsächlichen Betriebsbedingungen nachweisen.

Die Statusanzeige ist kein Einsatznachweis

Bei der Bereitstellung eines TeamCity-macOS-Build-Agenten sind mehrere voneinander unabhängige Zustände zu unterscheiden: Der Prozess kann installiert sein, ohne den Server zu erreichen. Ein verbundener Agent kann noch auf Freigabe warten. Und ein freigegebener Agent kann für eine bestimmte Build-Konfiguration ungeeignet sein, weil Anforderungen oder Werkzeuge nicht übereinstimmen.

Diese Trennung ist für die Fehlersuche entscheidend. Eine erfolgreiche Installation beweist weder, dass der Server erreichbar ist, noch dass der Agent in TeamCity einsatzbereit ist. Ebenso bestätigt eine Online-Anzeige nicht, dass der Agent die benötigte Xcode-Konfiguration besitzt oder einen Build im geforderten Benutzerkontext ausführen kann. Die TeamCity-Dokumentation zu Agent-Installation, Status und Freigabe beschreibt diese Status- und Autorisierungsschritte.

Führen Sie die Prüfung deshalb als nachvollziehbare Folge von Übergängen durch: Installation, Verbindung, Freigabe, Kompatibilität, Werkzeugprüfung und Test-Build. Notieren Sie bei jedem Übergang den beobachteten Status und die zugehörigen Protokolle. So lässt sich später unterscheiden, ob ein Fehler beim Start, beim Verbindungsaufbau, bei der Aufgabenzuordnung oder erst beim Kompilieren entstand.

Erst Verbindung und Freigabe eindeutig klären

Wie installieren Sie den TeamCity-Build-Agent auf einem Mac? Laden Sie das Agent-Paket über den in Ihrer TeamCity-Umgebung vorgesehenen Weg, richten Sie die Serveradresse und die Agent-Konfiguration ein und starten Sie den Agent nach der offiziellen Anleitung. Die Installationsanleitung für TeamCity-Agenten und die Konfigurationsreferenz zur Agent-Installation sind dafür maßgeblich. Verwenden Sie die Dokumentation, die zu Ihrer tatsächlichen TeamCity-Installation passt, statt Einstellungen aus einem fremden Beispiel ungeprüft zu übernehmen.

Prüfen Sie danach zuerst, ob der Mac den konfigurierten Server unter der eingetragenen Adresse erreichen kann. Kontrollieren Sie Hostname und Port anhand der Umgebung, die der Agent tatsächlich verwendet. Bei einem Netzwerkfehler helfen weder eine erneute Freigabe noch eine Änderung der Xcode-Schritte: Zuerst muss die Verbindung möglich sein.

Wenn der Server erreichbar ist, vergleichen Sie die Agent-Konfiguration mit dem erwarteten Agent-Namen und den Authentifizierungsinformationen. Lesen Sie anschließend das Agent-Protokoll, statt sich allein auf die Installationsausgabe zu verlassen. Die sichtbare Meldung im Protokoll sollte erklären, ob der Agent den Server kontaktieren konnte und ob er auf eine Aktion in der TeamCity-Verwaltung wartet.

Prüfen Sie dann im Administrationsbereich den Status und die Freigabe des Agenten. Ein Agent, der noch nicht autorisiert oder deaktiviert ist, darf nicht mit einem für Builds verfügbaren Agenten gleichgesetzt werden. Halten Sie fest, wann sich sein Status geändert hat. Diese Zeitangabe hilft dabei, Protokolle auf Mac und Server mit demselben Ereignis zu vergleichen.

Der Agent ist verbunden, aber Builds starten nicht: Was ist zuerst zu prüfen? Stellen Sie fest, ob er freigegeben und aktiviert ist. Danach untersuchen Sie die Anforderungen des Build-Schritts und die vom Agent gemeldeten Eigenschaften. Die Freigabe bestätigt nur, dass TeamCity den Agenten verwenden darf; sie bestätigt nicht, dass die benötigten Werkzeuge oder Plattformmerkmale vorhanden sind.

Kompatibilität und Xcode vor dem ersten Build abgleichen

Ein häufiger Fehler entsteht, wenn die Build-Konfiguration eine Fähigkeit voraussetzt, die der Agent nicht meldet. Prüfen Sie deshalb die Agent-Anforderungen der Konfiguration und gleichen Sie sie mit den tatsächlichen Eigenschaften des Mac ab. TeamCity bietet Angaben zu vordefinierten Agent-Parametern und zur Konfiguration von Anforderungen; die Dokumentation zu Build-Agent-Anforderungen erläutert, wie solche Bedingungen die Zuordnung beeinflussen. Die Referenz zu vordefinierten Build-Parametern hilft, die gemeldeten Werte zu identifizieren.

Achten Sie insbesondere darauf, ob eine Anforderung eine bestimmte Eigenschaft exakt erwartet, ob sie auf einen anderen Wert prüft oder ob sie an eine selbst definierte Umgebungsvariable gebunden ist. Eine Abweichung kann dazu führen, dass der Agent online bleibt, aber für die betreffende Konfiguration nicht als kompatibel gilt. Ändern Sie Anforderungen nicht nur, um einen Build „irgendwie“ startbar zu machen: Prüfen Sie zuerst, ob die Änderung fachlich zulässig ist und die gewünschte Plattform weiterhin abdeckt.

Anschließend untersuchen Sie die Xcode-Auswahl auf dem Mac. Ein System kann mehrere Installationen oder eine abweichende Auswahl der Kommandozeilenwerkzeuge haben. Prüfen Sie den Pfad der aktiven Werkzeuge mit xcode-select -p und kontrollieren Sie die tatsächliche Xcode-Ausgabe mit dem vorgesehenen Kommandozeilenwerkzeug. Die Apple-Anleitung zur Konfiguration der Kommandozeilenwerkzeuge erklärt die Auswahl; die Referenz zu Xcode-Kommandozeilenwerkzeugen beschreibt die verfügbaren Befehle.

TeamCity kann für Xcode-Projekte eigene Build-Schritte und Einstellungen verwenden. Vergleichen Sie deshalb die im Build-Schritt festgelegte Auswahl mit dem Werkzeugpfad des Mac. Die TeamCity-Anleitung für Xcode-Projekte ist die Referenz für die Konfiguration. Installierte Versionen oder vermeintliche Kompatibilität sollten nicht aus einer allgemeinen Liste abgeleitet werden: Maßgeblich sind die aktuelle Dokumentation, die tatsächliche Agent-Umgebung und ein Build des Zielprojekts.

Die Tabelle grenzt Ursachen ein; sie ersetzt nicht die Prüfung der Protokolle. Insbesondere Netzwerkfehler, falsche Konfiguration und ausstehende Freigabe können im ersten Moment ähnlich wirken, erfordern aber unterschiedliche Maßnahmen.

Automatischen Start im wirklichen Betriebskontext prüfen

Wie richten Sie den automatischen Start eines TeamCity-Agenten unter macOS ein? Verwenden Sie die Startmethode, die zur TeamCity-Installation und zur Betriebsweise des Macs passt, und testen Sie sie nach einem Neustart oder einer erneuten Anmeldung. Die Dokumentation zum Starten von TeamCity-Agenten beschreibt den Agent-Start. Ob ein Agent als LaunchAgent oder über einen anderen vorgesehenen Startweg betrieben werden soll, hängt jedoch von der verwendeten Konfiguration und dem erforderlichen Benutzerkontext ab.

Wenn ein manueller Start funktioniert, der Agent nach einem Neustart aber fehlt, prüfen Sie zunächst, ob der Startprozess überhaupt ausgeführt wurde. Kontrollieren Sie anschließend, unter welchem Benutzer der Prozess läuft, ob dieser Benutzer Zugriff auf Agent-Dateien und benötigte Werkzeuge besitzt und ob die Startprotokolle einen Verbindungsversuch zeigen. So unterscheiden Sie „Prozess wurde nicht gestartet“ von „Prozess startete, kann den Server aber nicht erreichen“.

Berücksichtigen Sie außerdem, ob der Build eine grafische Sitzung oder eine bestimmte Benutzerumgebung voraussetzt. Ein Dienst, der in einem anderen Sitzungskontext startet als der manuelle Test, kann andere Umgebungsvariablen, Zugriffsrechte oder verfügbare Werkzeuge vorfinden. Leiten Sie daher nicht aus einem erfolgreichen Agent-Start ab, dass jede Art von iOS- oder macOS-Build in diesem Kontext funktioniert. Testen Sie die geplanten Aufgaben mit derselben Startweise, die später im Betrieb gelten soll.

Bei Xcode-Aufgaben mit Simulatoren oder physischen Geräten müssen Sie zusätzlich den tatsächlichen Ausführungsweg prüfen. Die Apple-Dokumentation zum Ausführen von Apps auf simulierten oder physischen Geräten beschreibt die relevanten Ausführungsarten. Verifizieren Sie für das eigene Projekt, ob Zielplattform, Berechtigungen und benötigter Sitzungskontext erfüllt sind; eine allgemeine macOS-Agent-Verbindung belegt das nicht.

Die Bereitstellung mit einem reproduzierbaren Build abnehmen

Eine belastbare Abnahme besteht aus einer zusammenhängenden Probe, nicht aus einem Screenshot der Agent-Übersicht. Verwenden Sie einen repräsentativen Build aus dem tatsächlichen Projekt und halten Sie die folgenden Ergebnisse fest:

1. Verbindung dokumentieren: Erfassen Sie Serverziel, Agent-Namen und den Status in der TeamCity-Verwaltung. Notieren Sie, ob der Agent nach dem Start erreichbar war und ob sein Protokoll Verbindungsprobleme meldete.
2. Freigabe bestätigen: Prüfen Sie, ob der Agent autorisiert und aktiviert ist. Halten Sie fest, wann der Status erreicht wurde, damit sich ein späterer Fehler zeitlich zuordnen lässt.
3. Anforderungen abgleichen: Vergleichen Sie die Agent-Eigenschaften mit den Anforderungen der konkreten Build-Konfiguration. Bewahren Sie die relevanten Parameter und die Entscheidung über abweichende Bedingungen auf.
4. Werkzeugkette nachweisen: Protokollieren Sie den aktiven Xcode-Pfad und die verwendete Xcode-Konfiguration. Kontrollieren Sie, dass der TeamCity-Build-Schritt dieselbe beabsichtigte Werkzeugauswahl verwendet.
5. Repräsentativen Build ausführen: Starten Sie eine Konfiguration, die typische Projektaktionen und das vorgesehene Ziel abdeckt. Prüfen Sie Build-Protokoll und erzeugtes Artefakt; bei Simulator- oder Geräteaufgaben testen Sie den tatsächlichen Ausführungspfad.
6. Wiederanlauf testen: Prüfen Sie den Agent-Start nach dem vorgesehenen Neustart- oder Anmeldeablauf. Bestätigen Sie anschließend erneut Verbindung, Freigabe und erfolgreiche Aufgabenzuordnung.

Wie bestätigen Sie, dass ein Xcode-Build den richtigen Mac-Agenten verwendet? Prüfen Sie in der Build-Ausführung die Zuordnung zum Agenten, vergleichen Sie die protokollierten Agent-Eigenschaften mit den Anforderungen und verifizieren Sie den Xcode-Pfad, den der Schritt tatsächlich verwendet. Der Build ist erst dann aussagekräftig, wenn zusätzlich das erwartete Artefakt oder Testergebnis vorliegt.

Speichern Sie die Agent-Statusanzeige, relevante Protokollausschnitte, die Build-Konfiguration und das Ergebnis gemeinsam als Abnahmebeleg. Diese Aufzeichnungen erleichtern später die Fehlersuche, wenn ein Agent nach einer Änderung an der Startumgebung offline geht oder eine Konfiguration nicht mehr kompatibel ist. Legen Sie auch fest, wer bei einer Abweichung Agent-Eigenschaften, Freigabe und Build-Anforderungen prüfen darf. Damit bleiben Änderungen nachvollziehbar und der Betrieb hängt nicht von einer einzelnen Person ab.

Den passenden Mac-Betrieb für TeamCity festlegen

Ein selbst verwalteter Mac kann sinnvoll sein, wenn das Unternehmen Hardware, Netzwerkzugang und Wartungsfenster selbst kontrollieren muss oder Builds physische Schnittstellen benötigen. Dafür müssen IT-Teams Beschaffung, Gerätelebenszyklus, macOS-Pflege, Zugriffsschutz und Wiederherstellung selbst organisieren. Ein allgemeiner Rechnerpool oder eine Entwicklungsmaschine ist nicht automatisch eine geeignete CI-Ressource: Die TeamCity-Aufgaben benötigen einen stabilen Agent-Start, klare Berechtigungen und eine dokumentierte Werkzeugkette.

Ein gemieteter Mac kann eine Option sein, wenn ein Team zeitweise zusätzliche macOS-Kapazität benötigt oder vor einer Investition die Einbindung in TeamCity praktisch erproben möchte. Vor einer Entscheidung sollte die IT jedoch prüfen, wie Zugang, Benutzerkonten, Datenlöschung, Netzwerkpfad und Verantwortlichkeiten geregelt sind. DSGVO-Anforderungen und interne Sicherheitsrichtlinien müssen anhand der konkreten Vertrags- und Betriebsbedingungen bewertet werden; daraus lässt sich keine pauschale Konformität eines beliebigen Dienstes ableiten. Für Teams, die Einsatzmodell und Zugriff zunächst abgrenzen möchten, bietet der Überblick zu den Mac-Umgebungen einen Einstieg in die weitere Bewertung.

Die Wahl sollte zudem von der Arbeitslast abhängen. Wenn Builds dauerhaft und planbar laufen und das Unternehmen Hardware langfristig auslasten kann, können Anschaffung und Eigenbetrieb passend sein. Wenn Kapazität nur für Projektphasen, Migrationen oder zeitlich begrenzte Tests gebraucht wird, kann eine befristete Bereitstellung den Bedarf besser abbilden. Wer einen Mac für TeamCity auswählt, sollte zuerst mit einem repräsentativen Build prüfen, ob Verbindung, Sitzungskontext, Werkzeugauswahl und Artefaktübergabe im vorgesehenen Betriebsmodell funktionieren.

Nach der technischen Abnahme lässt sich eine temporäre Mac-Miete von NowMini als Test- oder Übergangspfad prüfen. Sie kann den Aufwand vermeiden, sofort eigene Hardware zu beschaffen, verschiebt aber nicht die Verantwortung für TeamCity-Konfiguration, Zugriffsschutz, Xcode-Auswahl und Abnahme. Für einen langfristigen, konstant ausgelasteten Build-Betrieb oder Aufgaben mit zwingend erforderlichen physischen Schnittstellen kann ein eigener Mac die passendere Wahl sein. Klären Sie vor dem Start die verfügbaren Bedingungen und den Zugangsweg direkt über die Kontaktmöglichkeiten von NowMini, und führen Sie danach denselben dokumentierten Verbindung-, Werkzeug- und Build-Test durch wie bei einem selbst betriebenen Mac.