Jenkins dokumentiert bei Nodes mindestens zwei getrennte Speicherprüfungen: das Remote File System und das temporäre Verzeichnis in der offiziellen Node-Dokumentation. Ein Alarm kann deshalb auch dann bestehen bleiben, wenn Sie nur einen einzelnen Workspace löschen.

Symptom: Der Jenkins Mac Agent wird wegen Speicherknappheit offline gesetzt, doch nach dem Löschen eines Projekts bleibt der freie Speicher kritisch.

Schnellster Weg: Löschen Sie nicht den gesamten Arbeitsbereich. Erfassen Sie zuerst Workspace, Xcode-Daten, Simulatoren, Archive, Abhängigkeiten und temporäre Dateien getrennt. Wenn der Speicher danach weiter gegen Ihre Sperrgrenze läuft, reduzieren Sie die Parallelität, isolieren Sie den Signaturknoten und erweitern Sie die Mac-Kapazität.

Dieser Beitrag richtet sich an Sie, wenn Sie Jenkins Mac Agents, Speicherwarnungen und die Wiederinbetriebnahme von Build-Knoten verantworten.
Er ist ebenso für Plattformteams relevant, die Xcode-Caches, CI/CD-Wartezeiten und Bereinigungsregeln steuern.
Technische Leiter erhalten ein Entscheidungsmodell für zusätzliche feste oder bedarfsgesteuerte Remote-Mac-Kapazität.

Erst die Speicherquelle bestimmen, nicht den Workspace beschuldigen

Ein voller Jenkins Mac Agent ist zunächst ein Bestandsproblem. Der Begriff „Workspace“ beschreibt nur einen Teil des Dateisystems. In einer produktiven Umgebung können mindestens diese Bereiche unabhängig voneinander wachsen:

  • der Jenkins Remote-FS-Pfad mit Projekt-Workspaces;
  • ~/Library/Developer/Xcode/DerivedData;
  • Simulator-Gerätedaten und installierte Simulator Runtime;
  • Xcode Archives einschließlich dSYM und Exportdaten;
  • Swift Package Manager, CocoaPods, Homebrew, Git LFS und projektspezifische Caches;
  • temporäre Dateien, Logs und Zwischenprodukte;
  • Kopien im Jenkins Controller oder in einem externen Artefaktspeicher.

Beginnen Sie deshalb mit einer Aufnahme nach Pfad, Besitzer, Änderungszeit und Wachstum. Eine einzelne Momentaufnahme reicht nicht aus. Ein großer Ordner kann ein selten genutztes Archiv sein; ein kleinerer Ordner kann täglich unkontrolliert wachsen.

Für eine erste, nicht destruktive Übersicht genügt ein begrenzter Befehl:

du -sh "$JENKINS_HOME"/* "$HOME"/Library/Developer/Xcode/* /tmp/* 2>/dev/null

Die konkreten Pfade müssen Sie an den tatsächlichen Remote-FS-Pfad und den Benutzer des Agents anpassen. Prüfen Sie außerdem, ob Jenkins unter einem dedizierten Dienstkonto läuft. Eine Analyse unter Ihrem interaktiven Benutzer kann sonst ein falsches Bild liefern.

APFS-Anzeige nicht mit rückgewinnbarem Speicher verwechseln

macOS kann logische Dateigröße, tatsächlich belegten Speicher und kurzfristig wieder freigebbaren Speicher unterschiedlich ausweisen. Snapshots, offene Dateien und noch laufende Prozesse können dazu führen, dass eine Löschung nicht sofort dieselbe Veränderung in jeder Anzeige zeigt.

Ihre Entscheidung sollte deshalb nicht allein auf Finder-Kategorien beruhen. Vergleichen Sie:

  1. freie Kapazität vor der Bereinigung;
  2. belegte Größe des konkreten Verzeichnisses;
  3. offene Handles laufender Prozesse;
  4. freien Speicher nach Prozessabschluss;
  5. Verhalten nach einem kontrollierten Neustart des Agents.

Jenkins kann Node-Speicher überwachen und einen Node bei unzureichendem Speicher aus dem Betrieb nehmen. Die dafür relevanten Werte sind jedoch keine universellen Empfehlungen für jeden Build. Sie müssen aus Spitzenverbrauch, benötigter Installationsreserve und Wiederanlaufzeit Ihres Unternehmens abgeleitet werden. Die Jenkins-Verwaltungsdokumentation beschreibt die allgemeinen Verwaltungsfunktionen; die konkrete Schwelle gehört in Ihre Betriebsdokumentation.

Zweiter Schritt: verwaiste Workspaces und parallele Verzeichnisse prüfen

Pipeline-Workspaces werden automatisch zugewiesen. Bei parallelen Aufgaben können zusätzliche Verzeichnisse mit Suffixen entstehen; Jenkins dokumentiert dieses Verhalten in der Pipeline-Syntax. Das ist bei Multibranch-Projekten besonders relevant:

  • ein gelöschter Branch kann einen alten Workspace zurücklassen;
  • eine angepasste Workspace-Location kann außerhalb Ihrer erwarteten Prüfroutine liegen;
  • parallele Builds können getrennte Verzeichnisse verwenden;
  • ein abgebrochener Prozess kann temporäre Inhalte hinterlassen;
  • ein laufender Build kann Dateien noch verwenden, obwohl das zugehörige Projekt scheinbar abgeschlossen ist.

Prüfen Sie daher nicht nur den Namen eines Verzeichnisses. Ordnen Sie jeden Fund einem Job, Branch, Build und Prozess zu. Kontrollieren Sie die tatsächliche Workspace-Konfiguration sowie die Aufbewahrungsregeln des Jobs. Für Multibranch-Aufbewahrung können Sie die offizielle Jenkins-Dokumentation zur Build-Discard-Strategie heranziehen.

Kann Jenkins den Workspace nach dem Build automatisch löschen?

Ja, aber nicht pauschal und nicht ohne Rücksicht auf die Pipeline. Der Workspace Cleanup Plugin stellt mit cleanWs einen dokumentierten Pipeline-Schritt bereit siehe Plugin-Dokumentation. Entscheidend ist, wann und unter welchen Bedingungen Sie ihn ausführen.

Ein automatisches Löschen passt typischerweise zu einem Workspace, wenn:

  • der Quellcode jederzeit aus dem Repository reproduzierbar ist;
  • Abhängigkeiten aus einer kontrollierten Quelle wiederhergestellt werden können;
  • kein nachgelagerter Job auf dieselben Dateien zugreift;
  • Logs, Testberichte und signierte Artefakte außerhalb des Workspace gespeichert werden;
  • der zusätzliche Checkout- und Abhängigkeitsaufwand akzeptiert wird.

Eine automatische Löschung ist ungeeignet, wenn:

  • ein laufender paralleler Build denselben Pfad nutzt;
  • der Workspace die einzige Kopie eines nicht veröffentlichten Diagnoseergebnisses enthält;
  • ein eingeschränkter Netzwerkzugang die Wiederherstellung verzögert;
  • Sie gerade einen Fehler reproduzieren und die lokalen Zwischenprodukte benötigen;
  • der Job Signatur- oder Exportdaten fälschlich im Workspace ablegt.

Nutzen Sie für nicht zeitkritische Bereinigung einen kontrollierten Wartungszeitraum. Entfernen Sie niemals per globalem Shell-Befehl alle Verzeichnisse unterhalb des Jenkins-Pfads, solange der Node noch Builds annimmt. Nehmen Sie den Agent zunächst aus der Auftragsvergabe, warten Sie laufende Builds ab und protokollieren Sie die zu löschenden Pfade.

Dritter Schritt: Xcode-Daten nach Wiederaufbau und Beweiswert trennen

Die wichtigsten Xcode-Daten sind nicht gleichwertig. Ihre Bereinigung muss zwei Fragen beantworten: Kann der Inhalt reproduziert werden? Und benötigen Sie ihn später als Nachweis für einen Release oder eine Fehleranalyse?

DerivedData

DerivedData ist in vielen CI-Szenarien neu erzeugbar. Die Konsequenz einer Löschung ist jedoch ein erneuter Checkout, eine erneute Abhängigkeitsauflösung und eine vollständige oder teilweise Neukompilierung. Das kann die nächste Pipeline verlängern und bei einem Netzwerk- oder Paketquellenproblem sogar verhindern.

Löschen Sie DerivedData deshalb nur, wenn Sie den betroffenen Job identifiziert haben. Prüfen Sie vorab, ob mehrere Xcode-Versionen oder Branches denselben Speicherbereich verwenden. Bewahren Sie die Verzeichniszuordnung und den Zeitpunkt der Bereinigung auf, damit ein späterer Anstieg nicht fälschlich als neuer Fehler interpretiert wird.

Simulator-Geräte und Simulator Runtime

Gerätedaten und Runtime-Dateien sind getrennt zu beurteilen. Temporäre Simulator-Geräte können häufig neu erstellt werden. Eine Runtime oder ein zusätzliches Plattformkomponent kann dagegen erneut heruntergeladen oder aus einer geprüften Quelle importiert werden müssen. Apple beschreibt die Verwaltung zusätzlicher Xcode-Komponenten und deren Installation.

Vor einer Entfernung prüfen Sie daher:

  • Welche Jobs benötigen genau diese Runtime?
  • Ist sie im Ziel-Xcode verfügbar?
  • Kann der Agent die Komponente ohne manuelle Freigabe wiederherstellen?
  • Ist der Download in Ihrem Netzwerk erlaubt?
  • Gibt es einen dokumentierten Importweg für den Produktionsknoten?

Eine isolierte Bereinigung des Simulators kann sinnvoll sein. Das pauschale Entfernen aller Runtimes ist für einen produktiven Mac Agent dagegen ein Verfügbarkeitsrisiko.

Archives, dSYM und Veröffentlichungsnachweise

Archives sind keine gewöhnlichen Caches. Sie können für Export, Wiederveröffentlichung, Crash-Symbolication und interne Freigaben relevant sein. Apple beschreibt die Rolle von Debug-Informationen und dSYM in der Dokumentation zum Erstellen von Debug-Informationen.

Definieren Sie für Archives einen Eigentümer aus Release Engineering oder Qualitätssicherung. Dieser Eigentümer legt fest, welche Archive in der CI-Umgebung bleiben, welche in einen kontrollierten Artefaktspeicher verschoben werden und welche nach dokumentierter Freigabe entfernt werden. Ein Bereinigungsskript darf weder Keychain-Inhalte noch Signaturmaterial als allgemeine Cache-Dateien behandeln.

Vierter Schritt: Abhängigkeiten, Duplikate und Besitz klären

Ein weiterer Fehler ist die Annahme, dass nur der Agent Speicher verbraucht. Dieselbe Abhängigkeit kann gleichzeitig im Workspace, im Benutzerverzeichnis und im Artefaktspeicher liegen. Dadurch wird ein Agent zwar bereinigt, die eigentliche Speicherstrategie bleibt aber unverändert.

Erstellen Sie für jeden größeren Bestand eine kurze Eigentümertabelle:

Bestand Eigentümer Wiederaufbau möglich? Gemeinsame Nutzung Löschbedingung
Workspace Job- oder Plattformteam Meist ja, nach Prüfung Branch- oder Job-spezifisch Job abgeschlossen und kein Prozess aktiv
DerivedData CI-Plattform Häufig ja Abhängig von Xcode und Job Wachstum über definierter Grenze
Simulator Runtime Plattformteam Nur bei gesicherter Quelle Mehrere Jobs möglich Nicht benötigte Xcode-Linie
Archive und dSYM Release-Verantwortliche Nicht als Beweisstück behandeln Release- und Supportteams Nach dokumentierter Aufbewahrung
Paket- und Tool-Caches Plattformteam Abhängig von Quelle Mehrere Projekte möglich Wiederherstellung getestet

Bei Swift Package Manager, CocoaPods, Homebrew und Git LFS sollten Sie zusätzlich feststellen, ob die Daten lokal, im Repository oder in einem Artefaktspeicher liegen. Nicht jede Wiederholung ist unnötig: Ein lokaler Cache kann einen eingeschränkten Build-Knoten stabilisieren. Er wird aber problematisch, wenn er ohne Besitzer und ohne Ablaufregel wächst.

Trennen Sie außerdem drei Verantwortungsbereiche:

  • Jenkins Controller: Metadaten, Logs und Pipeline-Zustände;
  • Mac Agent: Workspace, Toolchains und lokale Build-Caches;
  • Artefaktspeicher: signierte Ergebnisse, Archives, dSYM und Release-Nachweise.

Die Jenkins-Pipeline-Dokumentation hilft bei der Einordnung von Pipeline-Schritten. Sie ersetzt aber keine interne Regel darüber, wo ein signiertes Artefakt dauerhaft aufbewahrt werden muss.

Fünfter Schritt: Signierung und laufende Prozesse vor dem Löschen schützen

Eine fehlerhafte Bereinigung kann mehr beschädigen als einen Build. Das Löschen eines aktiven Workspace kann einen laufenden Checkout oder Testprozess unterbrechen. Das Entfernen eines Archives kann die spätere Fehleranalyse erschweren. Das Verändern der Keychain kann Signierung, Notarisierung oder Exportprozesse stören.

Behandeln Sie deshalb diese Bereiche grundsätzlich getrennt:

  • aktive Workspace-Dateien;
  • Xcode-Caches;
  • Simulator-Daten;
  • Archives und dSYM;
  • temporäre Logs;
  • Keychain, Zertifikate und Profile.

Signaturmaterial gehört nicht in ein allgemeines find- oder Löschmuster. Wenn ein Job Credentials oder Profile in einem bereinigten Pfad materialisiert, müssen Sie die Pipeline zuerst korrigieren. Apple erläutert den Zusammenhang zwischen Release-Artefakten und Verteilung in der Dokumentation zu Beta- und Release-Verteilung.

So führen Sie eine kontrollierte Bereinigung aus

  1. Neue Builds stoppen: Markieren Sie den Mac Agent als nicht verfügbar für neue Aufgaben. Warten Sie laufende Jobs ab.
  2. Bestand sichern: Speichern Sie Pfad, Eigentümer, Größe, Änderungszeit und zugehörigen Job in einem Bereinigungsprotokoll.
  3. Prozesse prüfen: Kontrollieren Sie, ob Xcode, Simulator, Git, Paketmanager oder Signaturprozesse noch auf den Bestand zugreifen.
  4. Reversiblen Kandidaten wählen: Beginnen Sie mit eindeutig reproduzierbaren Caches, nicht mit Archives oder Credentials.
  5. Begrenzt löschen: Verwenden Sie einen expliziten Pfad und keinen globalen Musterbefehl.
  6. Freien Speicher erneut messen: Warten Sie auf abgeschlossene Prozesse und vergleichen Sie die Werte mit der Ausgangsaufnahme.
  7. Build-Funktion testen: Führen Sie Checkout, Abhängigkeitsauflösung, normalen Build und Tests aus.
  8. Signaturpfad prüfen: Lassen Sie anschließend einen kontrollierten Signatur- und Exportlauf folgen.
  9. Node wieder freigeben: Erst wenn Build, Test, Signierung und Überwachung erfolgreich sind, darf der Agent wieder Aufträge annehmen.

Die Jenkins-Node-Dokumentation ist dabei die Referenz für das Entfernen und Wiederanbieten eines Agents. „Speicher ist frei“ ist kein ausreichendes Abnahmekriterium.

Sechster Schritt: Bereinigungsgrenze oder Kapazitätsproblem entscheiden

Die richtige Reaktion hängt nicht nur vom aktuellen Speicherstand ab. Erfassen Sie über mehrere Betriebszyklen:

  • tägliches Wachstum je Verzeichnis;
  • Speicherverbrauch während eines Spitzen-Builds;
  • Häufigkeit manueller Bereinigungen;
  • Zeit zur Wiederherstellung von Caches und Plattformkomponenten;
  • Build-Warteschlange während der Bereinigung;
  • Anzahl der Node-Ausfälle;
  • Aufwand für Archive, dSYM und Release-Nachweise.

Ihre Schwellenwerte müssen aus diesen Messwerten entstehen. Eine allgemeine Prozentzahl wäre für unterschiedliche Xcode-Versionen, Testmatrizen und Parallelitätsgrade nicht belastbar. Definieren Sie trotzdem drei Betriebszustände:

  • Warnung: Die Plattform erzeugt ein Ticket und erfasst die größten Wachstumsquellen.
  • Keine neuen Aufträge: Der Agent nimmt keine weiteren Builds an, laufende Jobs dürfen geordnet enden.
  • Manuelle Intervention: Sie starten die dokumentierte Bestandsaufnahme und entscheiden zwischen Bereinigung, Parallelitätsreduzierung oder Erweiterung.

Die Entscheidung für Bereinigung, Isolation oder mehr Remote-Mac-Kapazität

Nutzen Sie die folgenden Bedingungen statt einer pauschalen „mehr Speicher“-Entscheidung:

  • Wenn ein klar identifizierter, reproduzierbarer Cache wächst und die Wiederherstellung getestet ist, wählen Sie eine begrenzte automatische Bereinigung.
  • Wenn mehrere parallele Builds verwaiste Workspace-Suffixe erzeugen, wählen Sie Job-Aufbewahrung, Workspace-Lifecycle-Regeln und eine niedrigere Parallelität.
  • Wenn Archives, dSYM oder signierte Ergebnisse den größten Bestand bilden, wählen Sie einen kontrollierten Artefaktspeicher und einen getrennten Signaturknoten.
  • Wenn Simulator Runtimes oder Plattformkomponenten fehlen würden, wählen Sie eine geprüfte Komponentenverwaltung statt einer spontanen Löschung.
  • Wenn die Bereinigung regelmäßig die Build-Warteschlange verlängert, wählen Sie zusätzliche feste oder bedarfsgesteuerte Remote-Mac-Kapazität.
  • Wenn der Speicher trotz Bereinigung weiter anwächst, wählen Sie zuerst weniger Parallelität und danach eine Kapazitätserweiterung.
  • Wenn Sie physische Schnittstellen, lokale Peripherie oder dauerhaft hohe Last benötigen, wählen Sie einen eigenen Mac-Knoten statt einer kurzfristigen Mietlösung.
Befund Erste Maßnahme Nicht als Erstes tun Eskalation
Ein Cache wächst reproduzierbar Eigentümer und Ablaufregel festlegen Alle Benutzerverzeichnisse löschen Automatisierte, begrenzte Bereinigung
Workspace-Suffixe häufen sich Parallelität und Job-Lifecycle prüfen Aktive Verzeichnisse global entfernen Wartungsfenster oder Job-Isolation
Runtime fehlt nach Bereinigung Wiederherstellungsquelle testen Alle Simulatoren entfernen Isolierter Toolchain-Knoten
Archive belegen den Agent Release-Verantwortung und Archivierung klären Archive wie Cache behandeln Getrennter Signatur- oder Release-Knoten
Warnung kehrt trotz Bereinigung zurück Wachstum und Spitzenlast messen Nur die Warnschwelle erhöhen Zusätzlicher Remote Mac

Abnahme nach der Bereinigung dokumentieren

Ein erfolgreicher Löschvorgang ist erst dann eine erfolgreiche Maßnahme, wenn die Pipeline wieder verlässlich arbeitet. Verwenden Sie eine Abnahmeliste mit konkreten Belegen:

Prüfschritt Erwarteter Nachweis Freigabeentscheidung
Quellcode-Checkout Repository wird auf dem bereinigten Agent geladen Ohne Fehler fortfahren
Abhängigkeitsauflösung Pakete und Tools kommen aus der vorgesehenen Quelle Cache-Strategie bestätigen
Normaler Xcode-Build Build endet erfolgreich Agent technisch nutzbar
Tests mit Simulator Zielgerät oder Runtime wird korrekt erstellt Simulatorbestand ausreichend
Signierter Export Zertifikat, Profil und Keychain funktionieren Signaturpfad unverändert
Agent-Neustart Node verbindet sich wieder und meldet korrekten Speicher Wiederinbetriebnahme möglich
Monitoring Warnung verschwindet oder bleibt nachvollziehbar Kapazitätsentscheidung dokumentieren

Wenn die Signaturprüfung fehlschlägt, stoppen Sie die Freigabe und stellen Sie nicht einfach einen alten Workspace wieder her. Prüfen Sie zuerst Keychain-Zugriff, Profile, Umgebungsvariablen und den tatsächlichen Release-Pfad. Wenn der Build erfolgreich ist, aber der Speicher nach wenigen Zyklen erneut kritisch wird, liegt das Problem wahrscheinlich nicht in einem einzelnen verwaisten Ordner.

Ein eigenes Mac-Agent-Kapazitätsmodell für Jenkins hilft Ihnen, Wachstum, Parallelität und Ausfallreserve gemeinsam zu dokumentieren. Für Teams, die zwischen Kauf und temporärer Erweiterung abwägen, ist auch eine Mac-mini-Infrastruktur für Unternehmens-Builds ein sinnvoller Vergleichspunkt.

Bestehender Ansatz oder zusätzliche Remote-Mac-Kapazität?

Wenn Ihre aktuelle Lösung aus einem einzelnen lokalen Mac mini als gemeinsamem Build-Knoten besteht, entstehen oft drei konkrete Nachteile: Ein Hardwareausfall blockiert mehrere Pipelines, Speicherbereinigung konkurriert mit laufenden Builds, und die Kapazität lässt sich bei Release-Spitzen nur langsam erweitern. Ein dauerhaft gemieteter eigener Rechner löst nicht automatisch die Verantwortung für Workspace-, Cache- und Archivregeln; eine kurzfristige Erweiterung kann jedoch die Warteschlange und den Druck auf den Signaturknoten entschärfen.

MACCOME passt vor allem dann in die Architektur, wenn Sie für einen begrenzten Zeitraum einen zusätzlichen echten Mac mit Remote-Zugriff, SSH- oder VNC-Zugang und vollständigen Administrationsrechten benötigen. Sie können den Knoten zunächst mit nicht produktiven Builds und einem kontrollierten Signaturszenario prüfen. Für dauerhaft hohe, planbare Last oder Anforderungen an physische Geräte bleibt ein eigener, fest betriebener Knoten die ehrlichere Wahl. Wenn dagegen Release-Spitzen, Migrationen oder die Entlastung eines überfüllten Agents im Vordergrund stehen, können Sie mit einem Remote-Mac-Buildknoten von MACCOME die Kapazität testen, ohne sofort weitere Hardware zu beschaffen.