Freigeben über


Selbstgehostete macOS-Agents

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Dieser Artikel enthält Anleitungen für die Verwendung der 3.x-Agent-Software mit Azure DevOps Services und aktuellen Versionen von Azure DevOps Server. Eine Liste der Azure DevOps Server-Versionen, die den 3.x-Agent unterstützen, finden Sie unter Wird der 3.x-Agent von Azure DevOps Server unterstützt?.

Zum Erstellen und Bereitstellen von Xcode-Apps oder Xamarin.iOS-Projekten benötigen Sie mindestens einen macOS-Agent. Mit diesem Agent können auch Java- und Android-Apps erstellt und bereitgestellt werden.

Hinweis

In diesem Artikel wird beschrieben, wie Sie einen selbstgehosteten Agent konfigurieren. Wenn Sie Azure DevOps Services verwenden und ein von Microsoft gehosteter Agent Ihre Anforderungen erfüllt, können Sie die Einrichtung eines selbstgehosteten macOS-Agents überspringen.

Informationen zu Agents

Wenn Sie bereits wissen, was ein Agent ist und wie er funktioniert, können Sie direkt mit den folgenden Abschnitten fortfahren. Wenn Sie jedoch mehr Hintergrundinformationen zu ihren Aufgaben und ihrer Funktionsweise benötigen, lesen Sie Azure Pipelines-Agents.

Überprüfen der Voraussetzungen

  • Unterstützte Betriebssysteme
    • x64
      • macOS 10.15 Catalina
      • macOS 11.0 „Big Sur“
      • macOS 12.0 „Monterey“
      • macOS 13.0 „Ventura“
      • macOS 14.0, „Sonoma“
    • ARM64
      • macOS 11.0 „Big Sur“
      • macOS 12.0 „Monterey“
      • macOS 13.0 „Ventura“
      • macOS 14.0, „Sonoma“
  • Git: Git 2.9.0 oder höher (die neueste Version wird empfohlen, die Sie problemlos mit Homebrew installieren können)
  • .NET: Die Agent-Software wird unter .NET 6 ausgeführt, installiert jedoch eine eigene Version von .NET, sodass es keine .NET-Voraussetzung gibt.
  • TFVC: Wenn Sie einen Build anhand eines TFVC-Repositorys erstellen, finden Sie weitere Informationen unter Voraussetzungen für TFVC.

Vorbereiten von Berechtigungen

Wenn Sie einen Build anhand eines Subversion-Repositorys erstellen, müssen Sie den Subversion-Client auf dem Computer installieren.

Sie sollten die Einrichtung des Agents beim ersten Mal manuell ausführen. Nachdem Sie ein Gefühl dafür bekommen haben, wie Agents funktionieren, oder wenn Sie die Einrichtung vieler Agents automatisieren möchten, sollten Sie die unbeaufsichtigte Konfiguration verwenden.

Informationssicherheit für selbstgehostete Agents

Der Benutzer, der den Agent konfiguriert, benötigt Pooladministratorberechtigungen, der Benutzer, der den Agent ausführt, jedoch nicht.

Die Ordner, die vom Agent gesteuert werden, sollten auf so wenige Benutzer wie möglich beschränkt werden, da sie Geheimnisse enthalten, die entschlüsselt oder exfiltriert werden können.

Der Azure Pipelines-Agent ist ein Softwareprodukt, das zum Ausführen von Code entwickelt wurde, der aus externen Quellen heruntergeladen wird. Es kann von Natur aus ein Ziel für RCE-Angriffe (Remote Code Execution, Remotecodeausführung) sein.

Daher ist es wichtig, das Bedrohungsmodell zu berücksichtigen, das jede einzelne Verwendung von Pipelines-Agents zum Ausführen von Aufgaben umgibt, und zu entscheiden, welche Mindestberechtigungen dem Benutzer, der den Agent ausführt, dem Computer, auf dem der Agent ausgeführt wird, den Benutzern, die Schreibzugriff auf die Pipelinedefinition haben, den Git-Repositorys, in denen die YAML-Datei gespeichert ist, oder der Gruppe von Benutzern, die den Zugriff auf den Pool für neue Pipelines steuern, erteilt werden können.

Es empfiehlt sich, die Identität, mit der der Agent ausgeführt wird, von der Identität mit Berechtigungen zum Verbinden des Agents mit dem Pool zu unterscheiden. Der Benutzer, der die Anmeldeinformationen (und andere Agent-bezogene Dateien) generiert, unterscheidet sich von dem Benutzer, der sie lesen muss. Daher ist es sicherer, den Zugriff auf den Agent-Computer selbst und die Agent-Ordner, die vertrauliche Dateien wie Protokolle und Artefakte enthalten, sorgfältig zu prüfen.

Es ist sinnvoll, nur DevOps-Administratoren und der Benutzeridentität, die den Agent-Prozess ausführt, Zugriff auf den Agent-Ordner zu gewähren. Administratoren müssen möglicherweise das Dateisystem untersuchen, um Buildfehler zu verstehen, oder Protokolldateien abrufen, um Azure DevOps-Fehler melden zu können.

Entscheiden, welchen Benutzer Sie verwenden möchten

In einem einmaligen Schritt müssen Sie den Agent registrieren. Jemand mit Berechtigung zum Verwalten der Agent-Warteschlange muss diese Schritte ausführen. Der Agent verwendet die Anmeldeinformationen dieser Person nicht im täglichen Betrieb, sie sind aber erforderlich, um die Registrierung abzuschließen. Erfahren Sie mehr über die Kommunikation von Agents.

Vergewissern Sie sich, dass der Benutzer über die Berechtigung verfügt

Vergewissern Sie sich, dass das Benutzerkonto, das Sie verwenden möchten, über die Berechtigung zum Registrieren des Agents verfügt.

Ist der Benutzer ein Azure DevOps-Organisationsbesitzer- oder TFS- oder Azure DevOps Server-Administrator? Dann müssen Sie nichts weiter tun: Sie verfügen über die nötige Berechtigung.

Andernfalls:

  1. Öffnen Sie einen Browser, und navigieren Sie zur Registerkarte Agent-Pools für Ihre Azure Pipelines-Organisation oder Azure DevOps Server- oder TFS-Server:

    1. Melden Sie sich bei Ihrem organization (https://dev.azure.com/{yourorganization}) an.

    2. Wählen Sie Azure DevOps, Organisationseinstellungen aus.

      Auswählen von „Organisationseinstellungen“

    3. Wählen Sie Agentpools aus.

      Registerkarte „Agentpools auswählen“

    1. Melden Sie sich bei Ihrer Projektsammlung unter http://your-server/DefaultCollection an.

    2. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Auswählen von „Sammlungseinstellungen“

    3. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“

    1. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Sammlungseinstellungen (2019)

    2. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“ (2019)

  2. Wählen Sie rechts auf der Seite den Pool aus, und klicken Sie dann auf Sicherheit.

  3. Sollte das Benutzerkonto, das Sie verwenden möchten, nicht angezeigt werden, bitten Sie einen Administrator, es hinzuzufügen. Der Administrator kann ein Agent-Pooladministrator, Azure DevOps-Organisationsbesitzer oder TFS- oder Azure DevOps Server-Administrator sein.

    Wenn es sich um einen Bereitstellungsgruppen-Agent handelt, kann der Administrator ein Bereitstellungsgruppenadministrator, Azure DevOps-Organisationsbesitzer oder TFS- oder Azure DevOps Server-Administrator sein.

    Sie können der Administratorrolle der Bereitstellungsgruppe in Azure Pipelines auf der Seite Bereitstellungsgruppen auf der Registerkarte Sicherheit einen Benutzer hinzufügen.

Hinweis

Wenn eine Meldung wie „Die Identität konnte leider nicht hinzugefügt werden. Versuchen Sie es mit einer anderen Identität.“ angezeigt wird, haben Sie wahrscheinlich die oben genannten Schritte für einen Organisationsbesitzer- oder TFS- oder Azure DevOps Server-Administrator ausgeführt. Sie müssen nichts weiter tun – Sie verfügen bereits über die Berechtigung zum Verwalten des Agentpools.

Herunterladen und Konfigurieren des Agents

Azure Pipelines

  1. Melden Sie sich beim Computer mit dem Konto an, für das Sie Berechtigungen wie im vorherigen Abschnitt erläutert vorbereitet haben.

  2. Melden Sie sich in Ihrem Webbrowser bei Azure Pipelines an, und navigieren Sie zur Registerkarte Agent-Pools:

    1. Melden Sie sich bei Ihrem organization (https://dev.azure.com/{yourorganization}) an.

    2. Wählen Sie Azure DevOps, Organisationseinstellungen aus.

      Auswählen von „Organisationseinstellungen“

    3. Wählen Sie Agentpools aus.

      Registerkarte „Agentpools auswählen“

    1. Melden Sie sich bei Ihrer Projektsammlung unter http://your-server/DefaultCollection an.

    2. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Auswählen von „Sammlungseinstellungen“

    3. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“

    1. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Sammlungseinstellungen (2019)

    2. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“ (2019)

  3. Wählen Sie den Standardpool, die Registerkarte Agents und dann Neuer Agent aus.

  4. Klicken Sie im Dialogfeld Agent abrufen auf macOS.

  5. Wählen Sie die Schaltfläche Herunterladen aus.

  6. Befolgen Sie die Anweisungen auf der Seite.

  7. Löschen Sie das erweiterte Attribut für die TAR-Datei: xattr -c vsts-agent-osx-x64-V.v.v.tar.gz.

  8. Entpacken Sie den Agent in das Verzeichnis Ihrer Wahl. Wechseln Sie mithilfe von cd zu diesem Verzeichnis, und führen Sie ./config.sh aus. Stellen Sie sicher, dass der Pfad zum Verzeichnis keine Leerzeichen enthält, da Tools und Skripts Leerzeichen nicht immer ordnungsgemäß mit Escapezeichen versehen.

Server-URL

Azure Pipelines: https://dev.azure.com/{your-organization}

Azure DevOps Server: https://{your_server}/tfs

Authentifizierungsart

Wählen Sie bei der Registrierung eines Agents aus den folgenden Authentifizierungstypen aus. Sie werden daraufhin von der Agent-Einrichtung aufgefordert, die spezifischen zusätzlichen Informationen anzugeben, die für jeden Authentifizierungstyp erforderlich sind. Weitere Informationen finden Sie unter Authentifizierungsoptionen für selbstgehostete Agents.

  • Persönliches Zugriffstoken
  • Alternativ: Stellen Sie mithilfe der Standardauthentifizierung eine Verbindung zu Azure DevOps Server oder TFS her. Wenn Sie Alternativ auswählen, werden Sie aufgefordert, Ihre Anmeldeinformationen anzugeben.

Interaktive Ausführung

Informationen dazu, ob der Agent im interaktiven Modus oder als Dienst ausgeführt werden muss, finden Sie im Artikel „Azure Pipelines-Agents“ unter Interaktiv vs. Dienst.

So führen Sie den Agent interaktiv aus

  1. Wenn Sie den Agent als Dienst ausgeführt haben, deinstallieren Sie den Dienst.

  2. Führen Sie den Agent aus.

    ./run.sh
    

Um den Agent neu zu starten, drücken Sie STRG+C, und führen Sie dann run.sh aus, um ihn neu zu starten.

Um Ihren Agent zu verwenden, führen Sie einen Auftrag mithilfe des Agent-Pools aus. Wenn Sie keinen anderen Pool ausgewählt haben, wird Ihr Agent im Pool Standard platziert.

Einmalige Ausführung

Für Agents, die für die interaktive Ausführung konfiguriert sind, können Sie festlegen, dass der Agent nur einen einzelnen Auftrag akzeptieren soll. So führen Sie diese Konfiguration aus

./run.sh --once

Agents in diesem Modus akzeptieren nur einen Auftrag und fahren dann ordnungsgemäß herunter, was für die Ausführung in einem Dienst wie Azure Container Instances nützlich ist.

Ausführung als Dienst des Typs „launchd“

Wir stellen Ihnen das./svc.sh-Skript zur Verfügung, mit dem Sie Ihren Agenten als launchd LaunchAgent-Dienst ausführen und verwalten können. Dieses Skript wird generiert, nachdem Sie den Agent konfiguriert haben. Der Dienst hat Zugriff auf die Benutzeroberfläche, um Ihre Benutzeroberflächentests auszuführen.

Hinweis

Wenn Sie andere Ansätze bevorzugen, können Sie jede Art von Dienstmechanismus verwenden, die Sie bevorzugen. Weitere Informationen unter Dienstdateien.

Token

Im folgenden Abschnitt werden diese Token ersetzt:

  • {agent-name}

  • {tfs-name}

Beispielsweise haben Sie einen Agent (wie im vorherigen Beispiel gezeigt) mit dem Namen our-osx-agentkonfiguriert. In den folgenden Beispielen ist {tfs-name} entweder:

  • Azure Pipelines: der Name Ihrer Organisation. Wenn Sie z. B. eine Verbindung mit https://dev.azure.com/fabrikam herstellen, lautet der Dienstname vsts.agent.fabrikam.our-osx-agent

  • TFS: der Name Ihres lokalen TFS-Servers. Wenn Sie z. B. eine Verbindung mit http://our-server:8080/tfs herstellen, lautet der Dienstname vsts.agent.our-server.our-osx-agent

Befehle

Wechseln zum Agent-Verzeichnis

Wenn Sie beispielsweise im Unterordner myagent Ihres Basisverzeichnisses installiert haben:

cd ~/myagent$

Installieren

Befehl:

./svc.sh install

Dieser Befehl erstellt eine launchd-plist, die auf ./runsvc.sh verweist. Dieses Skript richtet die Umgebung ein (weitere Details im folgenden Abschnitt) und startet den Host des Agenten.

Start

Befehl:

./svc.sh start

Ausgabe:

starting vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

Die linke Zahl ist die PID, wenn der Dienst ausgeführt wird. Wenn die zweite Zahl nicht 0 ist, ist ein Problem aufgetreten.

Status

Befehl:

./svc.sh status

Ausgabe:

status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

Die linke Zahl ist die PID, wenn der Dienst ausgeführt wird. Wenn die zweite Zahl nicht 0 ist, ist ein Problem aufgetreten.

Beenden

Befehl:

./svc.sh stop

Ausgabe:

stopping vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Stopped

Deinstallieren

Vor der Deinstallation sollte immer ein Beendigungsbefehl ausgeführt werden.

Befehl:

./svc.sh uninstall

Automatische Anmeldung und Sperre

Normalerweise wird der Agent-Dienst erst ausgeführt, nachdem sich der Benutzer angemeldet hat. Wenn der Agent-Dienst beim Neustart des Computers automatisch gestartet werden soll, können Sie den Computer so konfigurieren, dass er sich automatisch anmeldet und beim Start eine Sperre aktiviert. Weitere Informationen finden Sie unter Apple-Support: So meldest du dich automatisch bei einem Mac-Benutzeraccount an.

Hinweis

Weitere Informationen finden Sie im Blog Terminally Geeky: use automatic login more securely. Die in diesem Blog erwähnte PLIST-Datei ist möglicherweise nicht mehr über die Quelle verfügbar, aber eine Kopie können Sie hier finden: Lifehacker – Make OS X load your desktop before you log in.

Aktualisieren von Umgebungsvariablen

Wenn Sie den Dienst konfigurieren, benötigt er eine Momentaufnahme einiger nützlicher Umgebungsvariablen für Ihren aktuellen Anmeldebenutzer, z. B. PATH, LANG, JAVA_HOME, ANT_HOME und MYSQL_PATH. Wenn Sie die Variablen aktualisieren müssen (z. B. nach der Installation einer neuen Software):

./env.sh
./svc.sh stop
./svc.sh start

Die Momentaufnahme der Umgebungsvariablen wird in der Datei .env im Stammverzeichnis des Agents gespeichert. Sie können diese Datei auch direkt ändern, um Änderungen an Umgebungsvariablen anzuwenden.

Ausführen von Anweisungen vor dem Starten des Diensts

Sie können auch eigene Anweisungen und Befehle ausführen, die beim Start des Diensts ausgeführt werden sollen. So können Sie beispielsweise die Umgebung einrichten oder Skripts aufrufen.

  1. Bearbeiten Sie runsvc.sh.

  2. Ersetzen Sie die folgende Zeile durch Ihre Anweisungen:

    # insert anything to setup env when running as a service
    

Dienstdateien

Wenn Sie den Dienst installieren, werden einige Dienstdateien eingerichtet.

PLIST-Dienstdatei

Eine PLIST-Dienstdatei wird erstellt:

~/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Beispiel:

~/Library/LaunchAgents/vsts.agent.fabrikam.our-osx-agent.plist

./svc.sh install generiert diese Datei aus dieser Vorlage: ./bin/vsts.agent.plist.template

SERVICE-Datei

./svc.sh start findet den Dienst durch Lesen der .service-Datei, die den Namen der oben beschriebenen PLIST-Dienstdatei enthält.

Alternative Dienstmechanismen

Wir stellen Ihnen das ./svc.sh-Skript als praktische Möglichkeit zum Ausführen und Verwalten Ihres Agenten als launchd LaunchAgent-Dienst zur Verfügung. Sie können jedoch jede Art von Dienstmechanismus verwenden, die Sie bevorzugen.

Sie können die oben beschriebene Vorlage verwenden, um das Generieren anderer Arten von Dienstdateien zu erleichtern. Sie können beispielsweise die Vorlage so modifizieren, dass sie einen Dienst generiert, der als Startdaemon ausgeführt wird, wenn Sie keine Benutzeroberflächentests benötigen und die automatische Anmeldung und Sperre nicht konfigurieren möchten. Weitere Informationen finden Sie unter Bibliothek für Apple-Entwickler: Creating Launch Daemons and Agents.

Ersetzen eines Agents

Um einen Agent zu ersetzen, führen Sie die Schritte unter Herunterladen und Konfigurieren des Agents erneut aus.

Wenn Sie einen Agent konfigurieren und dabei den Namen eines bereits vorhandenen Agents verwenden, werden Sie gefragt, ob Sie den vorhandenen Agent ersetzen möchten. Wenn Sie mit Y antworten, stellen Sie sicher, dass Sie den Agent entfernen (siehe unten), den Sie ersetzen. Andernfalls wird einer der Agents nach einigen Minuten des Konflikts heruntergefahren.

Entfernen und erneutes Konfigurieren eines Agents

So entfernen Sie den Agent

  1. Beenden und deinstallieren Sie den Dienst, wie im vorherigen Abschnitt erläutert.

  2. Entfernen Sie den Agent.

    ./config.sh remove
    
  3. Geben Sie Ihre Anmeldeinformationen ein.

Nachdem Sie den Agent entfernt haben, können Sie ihn erneut konfigurieren.

Unbeaufsichtigte Konfiguration

Der Agent kann ohne menschliche Interaktion über ein Skript eingerichtet werden. Sie müssen --unattended und die Antworten auf alle Fragen übergeben.

Um einen Agent zu konfigurieren, muss er die URL zu Ihrer Organisation oder Sammlung sowie die Anmeldeinformationen einer Person kennen, die zum Einrichten von Agents autorisiert ist. Alle anderen Antworten sind optional. Befehlszeilenparameter können stattdessen mithilfe einer Umgebungsvariablen angegeben werden: Geben Sie den Namen in Großbuchstaben ein, und stellen Sie VSTS_AGENT_INPUT_ voran. Geben Sie also beispielweise VSTS_AGENT_INPUT_PASSWORD anstelle von --password an.

Erforderliche Optionen

  • --unattended: Bei der Einrichtung des Agents werden keine Informationen angefordert, und alle Einstellungen müssen über die Befehlszeile bereitgestellt werden.
  • --url <url>: URL des Servers. Beispiel: https://dev.azure.com/myorganization oder http://my-azure-devops-server:8080/tfs.
  • --auth <type>: Authentifizierungstyp. Gültige Werte sind:
    • pat (persönliches Zugriffstoken): PAT ist das einzige Schema, das mit Azure DevOps Services funktioniert.
    • alt (Standardauthentifizierung)

Authentifizierungsoptionen

  • Wenn Sie --auth pat ausgewählt haben:
    • --token <token>: gibt Ihr persönliches Zugriffstoken an
    • PAT ist das einzige Schema, das mit Azure DevOps Services funktioniert.
  • Wenn Sie --auth negotiate oder --auth alt ausgewählt haben:
    • --userName <userName> – gibt einen Benutzernamen an
    • --password <password>: gibt ein Kennwort an

Pool- und Agent-Namen

  • --pool <pool>: Name des Pools, dem der Agent beitreten soll
  • --agent <agent>: Agent-Name
  • --replace: Option zum Ersetzen des Agents in einem Pool. Wenn ein anderer Agent mit dem gleichen Namen lauscht, tritt ein Konflikt auf

Einrichtung des Agents

  • --work <workDirectory>: Arbeitsverzeichnis, in dem Auftragsdaten gespeichert werden. Der Standardwert _work befindet sich im Stammverzeichnis des Agent-Verzeichnisses. Das Arbeitsverzeichnis gehört einem bestimmten Agent und darf nicht von mehreren Agents gemeinsam genutzt werden.
  • --acceptTeeEula: Option zum Akzeptieren des Endbenutzer-Lizenzvertrags für Team Explorer Everywhere (nur macOS und Linux)
  • --disableloguploads: legt fest, dass die Ausgabe des Konsolenprotokolls nicht an den Server gestreamt oder gesendet werden soll. Stattdessen können Sie sie nach Abschluss des Auftrags aus dem Dateisystem des Agent-Hosts abrufen.

Nur für die Bereitstellungsgruppe

  • --deploymentGroup: Konfiguriert den Agent als Bereitstellungsgruppen-Agent
  • --deploymentGroupName <name>: wird mit --deploymentGroup verwendet, um die Bereitstellungsgruppe anzugeben, der der Agent beitreten soll
  • --projectName <name>: wird mit --deploymentGroup verwendet, um den Projektnamen festzulegen
  • --addDeploymentGroupTags: wird mit --deploymentGroup verwendet, um anzugeben, dass Bereitstellungsgruppentags hinzugefügt werden sollen
  • --deploymentGroupTags <tags>: wird mit --addDeploymentGroupTags verwendet, um die durch Trennzeichen getrennte Liste von Tags für den Bereitstellungsgruppen-Agent anzugeben (beispielsweise „web, db“)

Nur für Umgebungen

  • --addvirtualmachineresourcetags: wird verwendet, um anzugeben, dass Umgebungsressourcentags hinzugefügt werden sollen
  • --virtualmachineresourcetags <tags>: wird mit --addvirtualmachineresourcetags verwendet, um die durch Trennzeichen getrennte Liste von Tags für den Umgebungsressourcen-Agent anzugeben (beispielsweise „web, db“)

./config.sh --help: listet immer die neuesten erforderlichen und optionalen Antworten auf.

Diagnose

Wenn Sie Probleme mit Ihrem selbstgehosteten Agent haben, können Sie versuchen, Diagnosen auszuführen. Nach dem Konfigurieren des Agents:

./run.sh --diagnostics

Dadurch wird eine Diagnosesuite ausgeführt, die Ihnen bei der Problembehandlung helfen kann. Das Diagnosefeature ist ab Agent-Version 2.165.0 verfügbar.

Netzwerkdiagnose für selbstgehostete Agents

Legen Sie den Wert von Agent.Diagnostic auf fest true, um zusätzliche Protokolle zu sammeln, die zur Behandlung von Netzwerkproblemen für selbstgehostete Agents verwendet werden können. Weitere Informationen finden Sie unter Netzwerkdiagnose für selbstgehostete Agents.

Hilfe zu anderen Optionen

So erfahren Sie mehr über andere Optionen

./config.sh --help

Die Hilfe enthält Informationen zu Authentifizierungsalternativen und zur unbeaufsichtigten Konfiguration.

Funktionen

Die Funktionen Ihres Agents werden katalogisiert und im Pool angekündigt, sodass ihm nur die Builds und Releases zugewiesen werden, die er bewältigen kann. Weitere Informationen finden Sie unter Funktionen von Build- und Release-Agents.

In vielen Fällen müssen Sie nach der Bereitstellung eines Agents Software oder Hilfsprogramme installieren. Im Allgemeinen sollten Sie alle Softwarekomponenten und Tools, die Sie auf Ihrem Entwicklungscomputer verwenden, auf Ihren Agents installieren.

Wenn Ihr Build beispielsweise die npm-Aufgabe enthält, wird der Build nur ausgeführt, wenn im Pool ein Build-Agent mit einer npm-Installation vorhanden ist.

Wichtig

Zu den Funktionen gehören alle Umgebungsvariablen und die Werte, die bei der Ausführung des Agents festgelegt werden. Wenn sich einer dieser Werte ändert, während der Agent ausgeführt wird, muss der Agent neu gestartet werden, um die neuen Werte zu übernehmen. Nachdem Sie neue Software auf einem Agent installiert haben, müssen Sie den Agent neu starten, damit die neue Funktion im Pool vorhanden ist und der Build ausgeführt werden kann.

Sie können Umgebungsvariablen als Funktionen ausschließen, indem Sie die Umgebungsvariable VSO_AGENT_IGNORE mit einer durch Trennzeichen getrennten Liste der zu ignorierenden Variablen festlegen.

Häufig gestellte Fragen

Wie kann ich sicherstellen, dass ich über die neueste Version des Agents verfüge?

  1. Navigieren Sie zur Registerkarte Agent-Pools:

    1. Melden Sie sich bei Ihrem organization (https://dev.azure.com/{yourorganization}) an.

    2. Wählen Sie Azure DevOps, Organisationseinstellungen aus.

      Auswählen von „Organisationseinstellungen“

    3. Wählen Sie Agentpools aus.

      Registerkarte „Agentpools auswählen“

    1. Melden Sie sich bei Ihrer Projektsammlung unter http://your-server/DefaultCollection an.

    2. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Auswählen von „Sammlungseinstellungen“

    3. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“

    1. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Sammlungseinstellungen (2019)

    2. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“ (2019)

  2. Klicken Sie auf den Pool, der den Agent enthält.

  3. Stellen Sie sicher, dass der Agent aktiviert ist.

  4. Navigieren Sie zur Registerkarte „Funktionen“:

    1. Wählen Sie auf der Registerkarte Agent-Pools den gewünschten Agent-Pool aus.

      Auswählen des gewünschten Agentpools unter „Agentpools“.

    2. Wählen Sie Agents und dann den gewünschten Agent aus.

      Auswählen der Option „Agents“ und des Agents.

    3. Wählen Sie die Registerkarte Funktionen aus.

      Auswählen der Registerkarte „Funktionen“.

      Hinweis

      Von Microsoft gehostete Agents zeigen keine Systemfunktionen an. Eine Liste der auf von Microsoft gehosteten Agents installierten Software finden Sie unter Verwenden eines von Microsoft gehosteten Agents.

    1. Wählen Sie auf der Registerkarte Agentpools den gewünschten Agentpool aus.

      Auswählen des gewünschten Pools.

    2. Wählen Sie Agents und dann den gewünschten Agent aus.

      Auswählen der Option „Agents“ und des gewünschten Agents.

    3. Wählen Sie die Registerkarte Funktionen aus.

      Registerkarte „Funktionen“ für den Agent.

    1. Wählen Sie auf der Registerkarte Agentpools den gewünschten Agentpool aus.

      Auswählen der gewünschten Registerkarte (2019)

    2. Wählen Sie Agents und dann den gewünschten Agent aus.

      Auswählen des gewünschten Agents (2019)

    3. Wählen Sie die Registerkarte Funktionen aus.

      Auswählen der Registerkarte „Funktionen“ (2019)

  5. Suchen Sie nach der Agent.Version-Funktion. Sie können diesen Wert anhand der neuesten veröffentlichten Agent-Version überprüfen. Weitere Informationen finden Sie unter Azure Pipelines-Agent. Suchen Sie auf der Seite nach der höchsten Versionsnummer.

  6. Jeder Agent aktualisiert sich automatisch, wenn er eine Aufgabe ausführt, die eine neuere Version des Agents erfordert. Wenn Sie einige Agents manuell aktualisieren möchten, klicken Sie mit der rechten Maustaste auf den Pool, und wählen Sie Alle Agents aktualisieren aus.

Kann ich meine Agents aktualisieren, die Teil eines Azure DevOps Server-Pools sind?

Ja. Ab Azure DevOps Server 2019 können Sie Ihren Server so konfigurieren, dass er auf einem lokalen Datenträger nach den Agent-Paketdateien sucht. Diese Konfiguration überschreibt die Standardversion, die zum Zeitpunkt der Veröffentlichung des Servers mitgeliefert wurde. Dieses Szenario gilt auch, wenn der Server keinen Zugriff auf das Internet hat.

  1. Laden Sie von einem Computer mit Internetzugriff die neueste Version der Agent-Paketdateien (als ZIP- oder TAR.GZ-Dateien) von der GitHub-Releaseseite des Azure Pipelines-Agents herunter.

  2. Übertragen Sie die heruntergeladenen Paketdateien auf jede Azure DevOps Server-Anwendungsebene mithilfe einer Methode Ihrer Wahl (z. B. USB-Laufwerk, Netzwerkübertragung usw.). Legen Sie die Agent-Dateien im folgenden Ordner ab:

  • Windows: %ProgramData%\Microsoft\Azure DevOps\Agents
  • Linux: usr/share/Microsoft/Azure DevOps/Agents
  • macOS: usr/share/Microsoft/Azure DevOps/Agents

Erstellen Sie den Ordner Agents, wenn dieser nicht vorhanden ist.

  1. Alles erledigt! Ihre Azure DevOps Server-Instanz verwendet nun die lokalen Dateien, wenn die Agents aktualisiert werden. Jeder Agent aktualisiert sich automatisch, wenn er eine Aufgabe ausführt, die eine neuere Version des Agents erfordert. Wenn Sie jedoch einige Agents manuell aktualisieren möchten, klicken Sie mit der rechten Maustaste auf den Pool, und wählen Sie Alle Agents aktualisieren aus.

Wie kann ich sicherstellen, dass ich über die neueste Version des Agents verfüge?

  1. Navigieren Sie zur Registerkarte Agent-Pools:

    1. Melden Sie sich bei Ihrem organization (https://dev.azure.com/{yourorganization}) an.

    2. Wählen Sie Azure DevOps, Organisationseinstellungen aus.

      Auswählen von „Organisationseinstellungen“

    3. Wählen Sie Agentpools aus.

      Registerkarte „Agentpools auswählen“

    1. Melden Sie sich bei Ihrer Projektsammlung unter http://your-server/DefaultCollection an.

    2. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Auswählen von „Sammlungseinstellungen“

    3. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“

    1. Wählen Sie Azure DevOps > Sammlungseinstellungen aus.

      Sammlungseinstellungen (2019)

    2. Wählen Sie Agentpools aus.

      Auswählen von „Agentpools“ (2019)

  2. Klicken Sie auf den Pool, der den Agent enthält.

  3. Stellen Sie sicher, dass der Agent aktiviert ist.

  4. Navigieren Sie zur Registerkarte „Funktionen“:

    1. Wählen Sie auf der Registerkarte Agent-Pools den gewünschten Agent-Pool aus.

      Auswählen des gewünschten Agentpools unter „Agentpools“.

    2. Wählen Sie Agents und dann den gewünschten Agent aus.

      Auswählen der Option „Agents“ und des Agents.

    3. Wählen Sie die Registerkarte Funktionen aus.

      Auswählen der Registerkarte „Funktionen“.

      Hinweis

      Von Microsoft gehostete Agents zeigen keine Systemfunktionen an. Eine Liste der auf von Microsoft gehosteten Agents installierten Software finden Sie unter Verwenden eines von Microsoft gehosteten Agents.

    1. Wählen Sie auf der Registerkarte Agentpools den gewünschten Agentpool aus.

      Auswählen des gewünschten Pools.

    2. Wählen Sie Agents und dann den gewünschten Agent aus.

      Auswählen der Option „Agents“ und des gewünschten Agents.

    3. Wählen Sie die Registerkarte Funktionen aus.

      Registerkarte „Funktionen“ für den Agent.

    1. Wählen Sie auf der Registerkarte Agentpools den gewünschten Agentpool aus.

      Auswählen der gewünschten Registerkarte (2019)

    2. Wählen Sie Agents und dann den gewünschten Agent aus.

      Auswählen des gewünschten Agents (2019)

    3. Wählen Sie die Registerkarte Funktionen aus.

      Auswählen der Registerkarte „Funktionen“ (2019)

  5. Suchen Sie nach der Agent.Version-Funktion. Sie können diesen Wert anhand der neuesten veröffentlichten Agent-Version überprüfen. Weitere Informationen finden Sie unter Azure Pipelines-Agent. Suchen Sie auf der Seite nach der höchsten Versionsnummer.

  6. Jeder Agent aktualisiert sich automatisch, wenn er eine Aufgabe ausführt, die eine neuere Version des Agents erfordert. Wenn Sie einige Agents manuell aktualisieren möchten, klicken Sie mit der rechten Maustaste auf den Pool, und wählen Sie Alle Agents aktualisieren aus.

Kann ich meine Agents aktualisieren, die Teil eines Azure DevOps Server-Pools sind?

Ja. Ab Azure DevOps Server 2019 können Sie Ihren Server so konfigurieren, dass er auf einem lokalen Datenträger nach den Agent-Paketdateien sucht. Diese Konfiguration überschreibt die Standardversion, die zum Zeitpunkt der Veröffentlichung des Servers mitgeliefert wurde. Dieses Szenario gilt auch, wenn der Server keinen Zugriff auf das Internet hat.

  1. Laden Sie von einem Computer mit Internetzugriff die neueste Version der Agent-Paketdateien (als ZIP- oder TAR.GZ-Dateien) von der GitHub-Releaseseite des Azure Pipelines-Agents herunter.

  2. Übertragen Sie die heruntergeladenen Paketdateien auf jede Azure DevOps Server-Anwendungsebene mithilfe einer Methode Ihrer Wahl (z. B. USB-Laufwerk, Netzwerkübertragung usw.). Legen Sie die Agent-Dateien im folgenden Ordner ab:

  • Windows: %ProgramData%\Microsoft\Azure DevOps\Agents
  • Linux: usr/share/Microsoft/Azure DevOps/Agents
  • macOS: usr/share/Microsoft/Azure DevOps/Agents

Erstellen Sie den Ordner Agents, wenn dieser nicht vorhanden ist.

  1. Alles erledigt! Ihre Azure DevOps Server-Instanz verwendet nun die lokalen Dateien, wenn die Agents aktualisiert werden. Jeder Agent aktualisiert sich automatisch, wenn er eine Aufgabe ausführt, die eine neuere Version des Agents erfordert. Wenn Sie jedoch einige Agents manuell aktualisieren möchten, klicken Sie mit der rechten Maustaste auf den Pool, und wählen Sie Alle Agents aktualisieren aus.

Wo kann ich mehr darüber erfahren, wie der Dienst des Typs „launchd“ funktioniert?

Bibliothek für Apple-Entwickler: Creating Launch Daemons and Agents

Ich führe eine Firewall aus und mein Code befindet sich in Azure Repos. Mit welchen URLs muss der Agent kommunizieren?

Wenn Sie einen Agent in einem sicheren Netzwerk hinter einer Firewall ausführen, stellen Sie sicher, dass der Agent die Kommunikation mit folgenden URLs und IP-Adressen einleiten kann.

Domänen-URL BESCHREIBUNG
https://{organization_name}.pkgs.visualstudio.com Azure DevOps-Paket-API für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://{organization_name}.visualstudio.com Für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://{organization_name}.vsblob.visualstudio.com Azure DevOps-Telemetriedaten für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://{organization_name}.vsrm.visualstudio.com Release Management-Dienste für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://{organization_name}.vssps.visualstudio.com Azure DevOps Platform Services für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://{organization_name}.vstmr.visualstudio.com Azure DevOps Test Management Services für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://*.blob.core.windows.net Azure Artifacts
https://*.dev.azure.com Für Organisationen, die die Domäne dev.azure.com verwenden
https://*.vsassets.io Azure Artifacts über CDN
https://*.vsblob.visualstudio.com Azure DevOps-Telemetriedaten für Organisationen, die die Domäne dev.azure.com verwenden
https://*.vssps.visualstudio.com Azure DevOps Platform Services für Organisationen, die die Domäne dev.azure.com verwenden
https://*.vstmr.visualstudio.com Azure DevOps Test Management Services für Organisationen, die die Domäne dev.azure.com verwenden
https://app.vssps.visualstudio.com Für Organisationen, die die Domäne {organization_name}.visualstudio.com verwenden
https://dev.azure.com Für Organisationen, die die Domäne dev.azure.com verwenden
https://login.microsoftonline.com Microsoft Entra-Anmeldung
https://management.core.windows.net Azure-Verwaltungs-APIs
https://vstsagentpackage.azureedge.net Agent-Paket

Um zu gewährleisten, dass Ihre Organisation mit vorhandenen Firewall- oder IP-Einschränkungen funktioniert, stellen Sie sicher, dass dev.azure.com und *dev.azure.com geöffnet sind, und aktualisieren Sie Ihre zugelassenen IP-Adressen basierend auf Ihrer IP-Version so, dass sie die folgenden IP-Adressen enthalten. Wenn sich die IP-Adressen 13.107.6.183 und 13.107.9.183 derzeit in der Positivliste befinden, lassen Sie sie dort, da sie nicht entfernt werden müssen.

IPv4-Bereiche

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6-Bereiche

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

Hinweis

Weitere Informationen zu zulässigen Adressen finden Sie unter Listen zulässiger Adressen und Netzwerkverbindungen.

Wie kann ich den Agent mit einem selbstsigniertem Zertifikat ausführen?

Ausführen des Agents mit selbstsigniertem Zertifikat

Wie kann ich den Agent hinter einem Webproxy ausführen?

Ausführen des Agents hinter einem Webproxy

Wie kann ich den Agent neu starten?

Wenn Sie den Agent interaktiv ausführen, lesen Sie die Neustartanweisungen unter Interaktiv ausführen. Wenn Sie den Agent als Dienst ausführen, folgen Sie den Schritten zum Beenden und anschließendem Starten des Agents.

Wie konfiguriere ich den Agent so, dass er einen Webproxy umgeht und eine Verbindung mit Azure Pipelines herstellt?

Wenn der Agent Ihren Proxy umgehen und eine direkte Verbindung mit Azure Pipelines herstellen soll, müssen Sie Ihren Webproxy so konfigurieren, dass der Agent auf die folgenden URLs zugreifen kann.

Für Organisationen, die die Domäne *.visualstudio.com verwenden:

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

Für Organisationen, die die Domäne dev.azure.com verwenden:

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

Um zu gewährleisten, dass Ihre Organisation mit vorhandenen Firewall- oder IP-Einschränkungen funktioniert, stellen Sie sicher, dass dev.azure.com und *dev.azure.com geöffnet sind, und aktualisieren Sie Ihre zugelassenen IP-Adressen basierend auf Ihrer IP-Version so, dass sie die folgenden IP-Adressen enthalten. Wenn sich die IP-Adressen 13.107.6.183 und 13.107.9.183 derzeit in der Positivliste befinden, lassen Sie sie dort, da sie nicht entfernt werden müssen.

IPv4-Bereiche

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6-Bereiche

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

Hinweis

Mit diesem Verfahren kann der Agent einen Webproxy umgehen. Ihre Buildpipeline und Skripts müssen weiterhin die Umgehung Ihres Webproxys für jede Aufgabe und jedes Tool verarbeiten, die bzw. das Sie in Ihrem Build ausführen.

Wenn Sie beispielsweise eine NuGet-Aufgabe verwenden, müssen Sie Ihren Webproxy so konfigurieren, dass er die Umgehung der URL für den Server unterstützt, der den verwendeten NuGet-Feed hostet.

Ich verwende TFS, und die URLs in den obigen Abschnitten funktionieren bei mir nicht. Wo finde ich Hilfe dazu?

Websiteeinstellungen und Sicherheit

Ich verwende TFS lokal und einige dieser Features werden nicht angezeigt. Warum nicht?

Einige dieser Features sind nur auf Azure Pipelines und noch nicht lokal verfügbar. Einige Features sind lokal verfügbar, wenn Sie ein Upgrade auf die neueste Version von TFS vorgenommen haben.

TFVC-Voraussetzungen

Wenn Sie TFVC verwenden, benötigen Sie auch Oracle Java JDK 1.6 oder höher. (Oracle JRE und OpenJDK sind für diesen Zweck nicht ausreichend.)

Das TEE-Plug-In wird für TFVC-Funktionen verwendet. Es verfügt über eine EULA, die Sie während der Konfiguration akzeptieren müssen, wenn Sie mit TFVC arbeiten möchten.

Da das TEE-Plug-In nicht mehr gepflegt wird und einige veraltete Java-Abhängigkeiten enthält, ist es ab Agent 2.198.0 nicht mehr in der Agent-Distribution enthalten. Das TEE-Plug-In wird jedoch während der Ausführung der Checkoutaufgabe heruntergeladen, wenn Sie ein TFVC-Repository auschecken. Das TEE-Plug-In wird nach der Auftragsausführung entfernt.

Hinweis

Hinweis: Aufgrund dieses Downloadmechanismus kann es sehr lange dauern, bis Ihre Checkoutaufgabe funktioniert.

Wenn der Agent hinter einem Proxy oder einer Firewall ausgeführt wird, müssen Sie den Zugriff auf die folgende Website sicherstellen: https://vstsagenttools.blob.core.windows.net/. Das TEE-Plug-In wird von dieser Adresse heruntergeladen.

Wenn Sie einen selbstgehosteten Agent verwenden und Probleme beim Herunterladen von TEE auftreten, können Sie TEE manuell installieren:

  1. Legen Sie die Umgebungs- oder Pipelinevariable DISABLE_TEE_PLUGIN_REMOVAL auf true fest. Diese Variable verhindert, dass der Agent das TEE-Plug-In nach dem Auschecken des TFVC-Repositorys entfernt.
  2. Laden Sie TEE-CLC Version 14.135.0 manuell von GitHub aus „Releases“ für Team Explorer Everywhere herunter.
  3. Extrahieren Sie den Inhalt des Ordners TEE-CLC-14.135.0 in <agent_directory>/externals/tee.