セルフホステッド macOS エージェント

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

Xcode アプリをビルドしてデプロイするには、少なくとも 1 つの macOS エージェントが必要です。 このエージェントは、Java アプリと Android アプリをビルドしてデプロイすることもできます。

エージェントについて

エージェントの概要と動作が既にわかっている場合は、次のセクションに進んでください。 ただし、それらが何を行い、どのように機能するかについてさらに背景を知りたい場合は、Azure Pipelines エージェント に関するページを参照してください。

前提条件を確認する

• サポートされているオペレーティング システム
  • x64
    • macOS 10.15 "Catalina"
    • macOS 11.0 "Big Sur"
    • macOS 12.0 "モントレー"
    • macOS 13.0 "ベンチュラ"
    • macOS 14.0 "Sonoma"
  • ARM64
    • macOS 11.0 "Big Sur"
    • macOS 12.0 "モントレー"
    • macOS 13.0 "ベンチュラ"
    • macOS 14.0 "Sonoma"

• Git - Git 2.9.0 以降 (推奨される最新バージョン - Homebrewで簡単にインストールできます)

• .NET - エージェント ソフトウェアは .NET 6 で実行されますが、.NET の前提条件がないように独自のバージョンの .NET をインストールします。
• TFVC - TFVC リポジトリからビルドする場合は、TFVC の前提条件を参照してください。

アクセス許可を準備する

Subversion リポジトリからビルドする場合は、Subversion クライアントをコンピューターにインストールする必要があります。

エージェントのセットアップは、初めて手動で実行する必要があります。 エージェントの動作を確認した後、または多数のエージェントの設定を自動化する場合は、無人構成を使用することを検討してください。

セルフホステッド エージェントの情報セキュリティ

エージェントを構成するユーザーにはプール管理者のアクセス許可が必要ですが、エージェントを実行しているユーザーには必要ありません。

エージェントによって制御されるフォルダーには、復号化または流出できるシークレットが含まれているため、できるだけ少数のユーザーに制限する必要があります。

Azure Pipelines エージェントは、外部ソースからダウンロードしたコードを実行するように設計されたソフトウェア製品です。 本質的には、リモート コード実行 (RCE) 攻撃のターゲットになる可能性があります。

そのため、パイプライン エージェントの個々の使用状況を取り巻く脅威モデルを考慮して作業を実行し、エージェントを実行しているユーザーに付与できる最小限のアクセス許可を、エージェントが実行されるマシンに対して、Pipeline 定義への書き込みアクセス権を持つユーザー (yaml が格納されている Git リポジトリ) に決定することが重要です。 または、新しいパイプラインのプールへのアクセスを制御するユーザーのグループ。

エージェントを実行している ID を、エージェントをプールに接続するアクセス許可を持つ ID とは異なって使用することをお勧めします。 資格情報 (およびその他のエージェント関連ファイル) を生成するユーザーは、それらを読み取る必要があるユーザーとは異なります。 そのため、エージェント マシン自体に付与されるアクセスと、ログや成果物などの機密ファイルを含むエージェント フォルダーを慎重に検討する方が安全です。

エージェント フォルダーへのアクセス権を付与するのは、DevOps 管理者と、エージェント プロセスを実行しているユーザー ID に対してのみ行うのが理にかなっています。 管理者は、ファイル システムを調査してビルドエラーを理解したり、ログ ファイルを取得して Azure DevOps のエラーを報告したりする必要がある場合があります。

使用するユーザーを決定する

1 回限りの手順として、エージェントを登録する必要があります。 エージェント キュー を管理 アクセス許可を持つユーザーは、次の手順を実行する必要があります。 エージェントは、日常的な操作ではこのユーザーの資格情報を使用しませんが、登録を完了する必要があります。 エージェントの通信方法の詳細を確認します。

ユーザーにアクセス許可があることを確認する

使用するユーザー アカウントに、エージェントを登録するアクセス許可があることを確認します。

ユーザーが Azure DevOps 組織の所有者か、TFS か Azure DevOps Server 管理者か。 ここで停止、許可があります。

それ以外の場合は：

1. ブラウザーを開き、Azure Pipelines 組織または Azure DevOps Server または TFS サーバーの エージェント プール タブに移動します。

   1. 組織にログインします (https://dev.azure.com/{yourorganization})。

   2. [Azure DevOps]、[組織の設定] を選択します。

      

   3. [エージェント プール] を選択します。

      

   1. プロジェクト コレクション (http://your-server/DefaultCollection) にサインインします。

   2. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   3. [エージェント プール] を選択します。

      

   1. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   2. [エージェント プール] を選択します。

      

2. ページの右側にあるプールを選択し、セキュリティをクリックします。

3. 使用するユーザー アカウントが表示されない場合は、管理者に追加してもらう必要があります。 管理者は、エージェント プール管理者、Azure DevOps 組織所有者、または TFS または Azure DevOps Server 管理者することができます。

   エージェント 展開グループの場合、管理者は、デプロイ グループ管理者、Azure DevOps 組織所有者、または TFS または Azure DevOps Server 管理者にすることができます。

   Azure Pipelinesの デプロイ グループ ページの セキュリティ タブで、デプロイ グループ管理者ロール ユーザーを追加できます。

エージェントをダウンロードして構成する

サーバー アドレス

認証の種類

エージェントを登録するときに、次の認証の種類から選択すると、エージェントのセットアップによって、各認証の種類に必要な特定の追加情報の入力が求められます。 詳細については、「セルフホステッド エージェント認証オプションの」を参照してください。

対話的な実行

エージェントを対話モードで実行するか、サービスとして実行するかのガイダンスについては、「エージェント: 対話型とサービスの」を参照してください。

エージェントを対話形式で実行するには:

1. エージェントをサービスとして実行している場合は、サービスをアンインストール 。

2. エージェントを実行します。

   ./run.sh
   

エージェントを再起動するには、Ctrl キーを押しながら C キーを押し、run.sh を実行して再起動します。

エージェントを使用するには、エージェントのプールを使用して ジョブを実行します。 別のプールを選択しなかった場合、エージェントは Default プールに配置されます。

1 回実行

対話形式で実行するように構成されたエージェントの場合は、エージェントに 1 つのジョブのみを受け入れるように選択できます。 この構成で実行するには:

./run.sh --once

このモードのエージェントは、1 つのジョブのみを受け入れてから、正常にスピンダウンします (Azure Container Instances などのサービスで実行する場合に便利です)。

起動されたサービスとして実行する

launchd LaunchAgent サービスとしてエージェントを実行および管理するための ./svc.sh スクリプトが用意されています。 このスクリプトは、エージェントを構成した後に生成されます。 サービスは UI テストを実行するための UI にアクセスできます。

トークン

次のセクションでは、これらのトークンが置き換えられます。

• {agent-name}

• {tfs-name}

たとえば、前の例に示すように、our-osx-agentという名前でエージェントを構成したとします。 次の例では、{tfs-name} は次のいずれかです。

• Azure Pipelines: 組織の名前。 たとえば、https://dev.azure.com/fabrikamに接続する場合、サービス名は vsts.agent.fabrikam.our-osx-agent

• TFS: オンプレミスの TFS AT サーバーの名前。 たとえば、http://our-server:8080/tfsに接続する場合、サービス名は vsts.agent.our-server.our-osx-agent

コマンド

エージェント ディレクトリに移動する

たとえば、ホーム ディレクトリの myagent サブフォルダーにインストールした場合は、次のようになります。

cd ~/myagent$

取り付ける

命令：

./svc.sh install

このコマンドは、./runsvc.shを指す launchd plist を作成します。 このスクリプトでは、環境を設定し (次のセクションで詳しく説明します)、エージェントのホストを起動します。

先頭

命令：

./svc.sh start

アウトプット：

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}

サービスが実行されている場合、左側の数値は pid です。 2 番目の数値が 0 でない場合は、問題が発生しました。

地位

命令：

./svc.sh status

アウトプット：

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}

サービスが実行されている場合、左側の数値は pid です。 2 番目の数値が 0 でない場合は、問題が発生しました。

止める

命令：

./svc.sh stop

アウトプット：

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

アンインストール

アンインストールする前に停止する必要があります。

命令：

./svc.sh uninstall

自動ログインとロック

通常、エージェント サービスはユーザーがログインした後にのみ実行されます。 マシンの再起動時にエージェント サービスを自動的に開始する場合は、起動時に自動的にログインしてロックするようにマシンを構成できます。 「起動時に自動的にログインするように Mac を設定する - Apple サポートを参照してください。

環境変数を更新する

サービスを構成すると、PATH、LANG、JAVA_HOME、ANT_HOME、MYSQL_PATHなど、現在のログオン ユーザーに役立つ環境変数のスナップショットが取得されます。 変数を更新する必要がある場合 (たとえば、新しいソフトウェアをインストールした後):

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

環境変数のスナップショットは、エージェントのルート ディレクトリの下 .env ファイルに格納されます。また、そのファイルを直接変更して環境変数の変更を適用することもできます。

サービスを開始する前に手順を実行する

独自の命令とコマンドを実行して、サービスの開始時に実行することもできます。 たとえば、環境を設定したり、スクリプトを呼び出したりすることができます。

1. runsvc.shを編集します。

2. 次の行を手順に置き換えます。

   # insert anything to setup env when running as a service
   

サービス ファイル

サービスをインストールすると、一部のサービス ファイルが配置されます。

.plist サービス ファイル

.plist サービス ファイルが作成されます。

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

例えば：

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

./svc.sh install は、このテンプレートからこのファイルを生成します: ./bin/vsts.agent.plist.template

.service ファイル

./svc.sh start は、上記の plist サービス ファイルへのパスを含む .service ファイルを読み取ってサービスを検索します。

代替サービス メカニズム

./svc.sh スクリプトは、launchd LaunchAgent サービスとしてエージェントを実行および管理するための便利な方法として提供されます。 ただし、任意の種類のサービス メカニズムを使用できます。

上記のテンプレートを使用して、他の種類のサービス ファイルの生成を容易にすることができます。 たとえば、UI テストが不要で、自動ログオンとロックを構成したくない場合は、起動デーモンとして実行されるサービスを生成するようにテンプレートを変更します。 Apple 開発者ライブラリ : 起動デーモンとエージェントの作成を参照してください。

エージェントを置き換える

エージェントを置き換えるには、ダウンロードに従って、エージェント の手順をもう一度構成します。

既に存在するエージェントと同じ名前を使用してエージェントを構成すると、既存のエージェントを置き換えるかどうかを確認するメッセージが表示されます。 Y答えた場合は、置き換えるエージェント (下記参照) を必ず削除してください。 そうしないと、数分間の競合の後、エージェントの 1 つがシャットダウンされます。

エージェントの削除と再構成

エージェントを削除するには:

1. 前のセクションで説明したように、サービスを停止してアンインストールします。

2. エージェントを削除します。

   ./config.sh remove
   

3. 資格情報を入力します。

エージェントを削除したら、再度構成できます。

無人構成

エージェントは、人間の介入なしでスクリプトから設定できます。 --unattended をクリアし、すべての質問に正しく回答する必要があります。

./config.sh --help 常に、必要な最新の応答と省略可能な応答が一覧表示されます。

診断

セルフホステッド エージェントで問題が発生した場合は、診断の実行を試すことができます。 エージェントを構成した後:

./run.sh --diagnostics

これは、問題のトラブルシューティングに役立つ可能性のある診断スイートを介して実行されます。 診断機能は、エージェント バージョン 2.165.0 以降で使用できます。

その他のオプションに関するヘルプ

その他のオプションについては、以下をご覧ください。

./config.sh --help

このヘルプでは、認証の代替方法と無人構成に関する情報を提供します。

資格

エージェントの機能はプールにカタログ化およびアドバタイズされるため、エージェントが処理できるビルドとリリースのみが割り当てられます。 ビルドおよびリリース エージェントの機能を参照してください。

多くの場合、エージェントをデプロイした後、ソフトウェアまたはユーティリティをインストールする必要があります。 通常は、開発用コンピューターで使用するソフトウェアやツールをエージェントにインストールする必要があります。

たとえば、ビルドに npm タスクが含まれている場合、npm がインストールされているプールにビルド エージェントがない限り、ビルドは実行されません。

FAQ

最新のエージェント バージョンを使用していることを確認するにはどうすればよいですか?

1. エージェント プールの [] タブに移動します。

   1. 組織にログインしてください (https://dev.azure.com/{yourorganization})。

   2. Azure DevOps、組織の設定を選択します。

      

   3. [エージェント プール] を選択します。

      エージェント プール タブを選択します。

   1. プロジェクト コレクション (http://your-server/DefaultCollection) にサインインします。

   2. [Azure DevOps ]、[コレクションの設定 ] を選択します。

      コレクションの設定を選びます。

   3. [エージェント プール] を選択します。

      

   1. [Azure DevOps]、 [コレクションの設定]の順に選択します。

      

   2. [エージェント プール] を選択します。

      

2. エージェントを含むプールをクリックします。

3. エージェントが有効になっていることを確認します。

4. [機能] タブに移動します。

   1. エージェント プールの [] タブで、目的のエージェント プールを選択します。

      

   2. エージェント を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

      手記

      Microsoft がホストするエージェントでは、システム機能は表示されません。 Microsoft ホスト型エージェントにインストールされているソフトウェアの一覧については、「Microsoft ホスト型エージェントを使用する」を参照してください。

   1. [エージェント プール] タブで、目的のプールを選択します。

      

   2. エージェント を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

   1. [エージェント プール] タブで、目的のプールを選択します。

      

   2. エージェント を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

5. Agent.Version 機能を探します。 この値は、公開されている最新のエージェント バージョンと照らして確認できます。 Azure Pipelines エージェントの を参照し、一覧に記載されている最も高いバージョン番号のページを確認してください。

6. 各エージェントは、新しいバージョンのエージェントを必要とするタスクを実行すると、自動的に更新されます。 一部のエージェントを手動で更新する場合は、プールを右クリックし、[すべてのエージェント更新] を選択します。

最新のエージェント バージョンを使用していることを確認するにはどうすればよいですか?

1. エージェント プールの [] タブに移動します。

   1. 組織にログインしてください (https://dev.azure.com/{yourorganization})。

   2. [Azure DevOps]、[組織の設定] の順に選びます。

      

   3. [エージェント プール] を選択します。

      

   1. プロジェクト コレクション (http://your-server/DefaultCollection) にサインインします。

   2. [Azure DevOps ]、[コレクションの設定 ] を選択します。

      [コレクションの設定を選択]

   3. [エージェント プール] を選択します。

      

   1. [Azure DevOps ]、[コレクションの設定 ] を選択します。

      

   2. [エージェント プール] を選択します。

      

2. エージェントを含むプールをクリックします。

3. エージェントが有効になっていることを確認します。

4. [機能] タブに移動します。

   1. エージェント プールの [] タブで、目的のエージェント プールを選択します。

      

   2. エージェント を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

      手記

      Microsoft がホストするエージェントでは、システム機能は表示されません。 Microsoft ホスト型エージェントにインストールされているソフトウェアの一覧については、「Microsoft ホスト型エージェントを使用する」を参照してください。

   1. [エージェント プール] タブで、目的のプールを選択します。

      

   2. エージェント を選択し、目的のエージェントを選択します。

      

   3. 機能 タブを選択します。

      

   1. [エージェント プール] タブで、目的のプールを選択します。

      

   2. エージェント を選択し、目的のエージェントを選択します。

      

   3. [機能] タブを選択します。

      

5. Agent.Version 機能を探します。 この値は、公開されている最新のエージェント バージョンと照らして確認できます。 Azure Pipelines エージェントの を参照し、一覧に記載されている最も高いバージョン番号のページを確認してください。

6. 各エージェントは、新しいバージョンのエージェントを必要とするタスクを実行すると、自動的に更新されます。 一部のエージェントを手動で更新する場合は、プールを右クリックし、[すべてのエージェント更新] を選択します。

起動されたサービスのしくみの詳細については、どこで確認できますか?

Apple Developer Library: 起動デーモンとエージェントの作成

自己署名証明書を使用してエージェントを実行するにはどうすればよいですか?

自己署名証明書を使用してエージェントを実行

Web プロキシの背後でエージェントを実行するにはどうすればよいですか?

Web プロキシ の背後でエージェントを実行する

エージェントを再起動する方法

エージェントを対話形式で実行している場合は、「対話形式で実行」の再起動手順を参照してください。 エージェントをサービスとして実行している場合は、次の手順に従ってエージェントを 停止 し、次に 開始 します。

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

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

TFVC の前提条件

TFVC を使用する場合は、Oracle Java JDK 1.6 以降も必要です。 (Oracle JRE と OpenJDK では、この目的には十分ではありません)。

TEE プラグイン は TFVC 機能に使用されます。 これには EULA が含まれており、TFVC を使用する予定の場合は、構成時に同意する必要があります。

TEE プラグインは維持されなくなり、古い Java 依存関係がいくつか含まれるため、エージェント 2.198.0 以降ではエージェントディストリビューションに含まれません。 ただし、TFVC リポジトリをチェックアウトしている場合は、チェックアウト タスクの実行中に TEE プラグインがダウンロードされます。 TEE プラグインは、ジョブの実行後に削除されます。

エージェントがプロキシまたはファイアウォールの背後で実行されている場合は、次のサイトへのアクセスを確実に受け入れる必要があります: https://vstsagenttools.blob.core.windows.net/。 TEE プラグインはこのアドレスからダウンロードされます。

セルフホステッド エージェントを使用していて、TEE のダウンロードに関する問題が発生している場合は、TEE を手動でインストールできます。

1. 環境変数またはパイプライン変数 DISABLE_TEE_PLUGIN_REMOVALtrueに設定します。 この変数により、TFVC リポジトリのチェックアウト後にエージェントが TEE プラグインを削除できなくなります。
2. Team Explorer Everywhere GitHub リリースから TEE-CLC バージョン 14.135.0 を手動でダウンロードします。
3. TEE-CLC-14.135.0 フォルダーの内容を <agent_directory>/externals/teeに抽出します。