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

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

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

エージェントの詳細

エージェントの概要としくみが既にわかっている場合は、次のセクションに進んでください。 ただし、その機能としくみの背景について詳しく知りたい場合は、「Azure Pipelines エージェント」を参照してください。

前提条件を確認する

• サポートされるオペレーティング システム
  • 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 以上 (最新バージョンをお勧めします - Homebrew で簡単にインストールできます)

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

アクセス許可を準備する

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

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

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

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

エージェントによって制御されるフォルダーは、含まれている機密情報の解読または漏洩を回避するために、できる限り少数のユーザーにアクセスを制限する必要があります。

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

したがって、作業を実行するパイプライン エージェントの個々の使用法に関する脅威モデルを考慮することが重要です。また、エージェントを実行しているユーザー、エージェントが実行されているマシン、パイプライン定義への書き込みアクセス権を持つユーザー、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の [配置グループ] ページの [セキュリティ] タブで、配置グループ管理者ロールにユーザーを追加できます。

エージェントのダウンロードと構成

サーバー URL

認証の種類

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

対話形式で実行する

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

エージェントを対話的に実行するには、次のようにします。

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

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

   ./run.sh
   

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

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

1 回実行する

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

./run.sh --once

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

launchd サービスとして実行する

launchd 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 でない場合は、問題が発生しました。

Status

コマンド:

./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 でない場合は、問題が発生しました。

Stop

コマンド:

./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

自動ログインとロック

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

環境変数を更新する

サービスを構成すると、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 ファイルを読み取ってサービスを検索します。

代替サービス メカニズム

launchd LaunchAgent サービスとしてエージェントを簡単に実行および管理するための ./svc.sh スクリプトが用意されています。 ただし、任意の種類のサービス メカニズムを使うこともできます。

先ほど説明したテンプレートを使うと、他の種類のサービス ファイルを簡単に生成できます。 たとえば、UI テストを必要とせず、自動ログオンとロックを構成しない場合は、起動デーモンとして実行されるサービスを生成するようにテンプレートを変更します。 「Apple Developer Library: Creating Launch Daemons and Agents」(Apple Developer Library: 起動デーモンとエージェントの作成) を参照してください。

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

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

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

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

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

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

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

   ./config.sh remove
   

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

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

無人構成

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

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

診断

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

./run.sh --diagnostics

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

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

その他のオプションについては、次の手順を実行します。

./config.sh --help

ヘルプには、認証の代替方法と無人構成に関する情報が記載されています。

機能

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

多くの場合、エージェントの配置後には、ソフトウェアまたはユーティリティのインストールが必要になります。 通常、開発用マシンで使用するソフトウェアやツールは、エージェントにインストールする必要があります。

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

よく寄せられる質問

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

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

launchd サービスのしくみの詳細についてはどこで確認できますか?

Apple Developer Library: Creating Launch Daemons and Agents (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 は、この目的に十分ではありません。)

TFVC 機能には TEE プラグインが使用されます。 これには EULA があり、TFVC を使用する予定の場合は、構成中に受け入れる必要があります。

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

エージェントがプロキシまたはファイアウォールの背後で稼働している場合は、このサイト (https://vstsagenttools.blob.core.windows.net/) へアクセスできるように同意する必要があります。 TEE プラグインはこのアドレスからダウンロードされます。

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

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