マシンランナーの Windows へのインストール

クラウド

Server v4.x

Server v3.x

このページの内容

このページでは、CircleCI のマシンランナーを Windows にインストールする方法を説明します。以下のインストール方法は、Windows Server 2019 と Windows Server 2016 の両方について、Datacenter エディションでテスト済みです。デスクトップエクスペリエンスとリモートデスクトップサービスを備えたその他のサーバー SKU でも動作するはずです。

以下のページでは、マシンランナーと、その依存関係 (Chocolatey、Git、Gzip など) を Windows サーバーにインストールする手順を説明します。

セットアップ中、CircleCI ジョブを実行する新しいローカル管理者ユーザーを作成します。そのため、Windows サーバーで、ローカルユーザーを作成し、そのユーザーのリモートログオンを許可できる必要があります。

また、このセットアップをドメイン環境で行う際には、Windows サーバーがドメインメンバーである必要があります。セルフホストランナーインスタンスは、ドメインコントローラーとして動作している Windows サーバーでは実行できません。

前提条件

マシンランナーをインストールし、ジョブを実行するには、root 権限があり、以下のユーティリティとツールがシステムにインストールされている必要があります：

coreutils (Linux のみ)
curl (macOS ではデフォルトでインストール済み)
sha256sum (プリインストールされていない場合):
- macOS の場合は、brew install coreutils ( Homebrew が必要)
- Ubuntu/Debain の場合は、`sudo apt install coreutils
- Red Hat の場合は、sudo yum install coreutils
tar
gzip
sepolicy ( RHEL 8 のみ)
rpmbuild ( RHEL 8 のみ)
コマンドラインからランナーをインストールする場合は、 CircleCI CLIを使用します。

セルフホストランナーの利用条件

1. ネームスペースとリソースクラスの作成

セルフホストランナーをインストールするには、名前空間とリソースクラストークンを作成する必要があります。リソースクラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。名前空間やリソースクラスについては、コンセプトのページを参照してください。

お客様のランナーは、インベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。

CircleCI Web アプリで、Self-Hostd Runners に移動します。
組織でセルフホストランナーを初めて使用する場合、ファーストステップとしてまず名前空間を作成する必要があります。 作成できる名前空間は、各組織につき 1 つのみです。 必須ではありませんが、 CircleCI のアカウント名を小文字で使用することを推奨します。 CircleCI は UI でデフォルトで推奨される名前空間として組織名を入力します。

もし、お客様の組織が既に Orb を使用しているのであれば、新しい名前空間を作らないでください。その代わりに、お客様の組織が Orb に使用している名前空間を入力してください。
2つ目の入力フィールドには、セルフホスト・ランナー・リソース・クラスの名前を入力します。
リソースクラストークンをコピーし保存します。セルフホストランナーはこのトークンを使って関連するリソースクラスの作業を要求します。

トークンは再取得できないので、必ず安全な場所に保管してください。
Linux、macOS、または Windows 上でのセルフホスト型ランナーのセットアップに特化したインストール手順については、「Machine」タブを選択してください。これらのプラットフォーム固有の手順は、このインストールガイドの次のセクションにも含まれています。

Figure 1. Web アプリによるマシンランナーのインストール
新しいリソースクラスの設定コードが提供されます。既存の .circleci/config.yml がある場合は、既存の jobs セクションの下に新しいリソースクラスを追加してください。既存のファイルがない場合は、 jobs セクション全体を追加します。既存の .circleci/config.yml ファイルがない場合は、ファイルを作成し、すべてのコードをコピーします。

サーバー用のセルフホストランナー をインストールする場合は、サーバー API キーを使って CircleCI CLI を設定する必要があります。 circleci setup を実行して CLI を設定し、必要に応じて新しい API トークンを提供するオプションにアクセスします。

セルフホストランナーをインストールするには、下記手順を実行し、名前空間と認証トークンを作成する必要があります。リソースクラスとトークンを作成するには、VCS プロバイダーの組織管理者である必要があります。

お客様のランナーは、 Web アプリ内のインベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。

組織のセルフホストランナーの名前空間を作成します。 作成できる名前空間は、各組織につき 1 つのみです。 CircleCI の組織のアカウント名を小文字で使用することを推奨します。既に Orb を使用している場合は、Orb で使用しているのと同じ名前空間にします。

下記のコマンドを使って名前空間を作成します。
```
circleci namespace create <name> --org-id <your-organization-id>
```
TIP: 組織に既にネームスペースがある場合、上記のコマンドを実行して別のネームスペースを作成すると、エラーが表示されます。エラーメッセージは既存のネームスペースの名前を返します。この場合、既存のネームスペースを使用して、以下の手順 2 に進みます。
次のコマンドを実行して、セルフホストランナーの名前空間用のリソースクラスを作成します。
```
circleci runner resource-class create <namespace>/<resource-class> <description> --generate-token
```
<namespace> と <resource-class> は、それぞれお客様の orgネームスペースと希望するリソースクラス名に置き換えてください。オプションで説明を追加することもできます。

例: circleci runner resource-class create my-namespace/my-resource-class my-description --generate-token.

リソースクラストークンは、ランナーリソースクラスが正常に作成された後に返されます。

トークンは再取得できないので、必ず安全な場所に保管してください。

2. 起動エージェントのバージョンを設定する（サーバーのみ）

CircleCI クラウド用の Windows マシンランナーをインストールする場合は、次のステップに進んでください。

For server v3.1.0 and up, use the table below to find the compatible machine runner launch-agent version for the version of server you are running:

Server version	Launch agent version
3.0	Runner not supported
3.1	1.0.11147-881b608
3.2	1.0.19813-e9e1cd9
3.3	1.0.29477-605777e
3.4	1.1.73695-40bf772
4.0	1.1.73695-40bf772
4.1	1.1.73695-40bf772
4.2	1.1.73695-40bf772
4.3	1.1.73189-8792751

Substitute <launch-agent-version> with your launch-agent version for server and run the following:

$Env:agentVer = "<launch-agent-version>"

3. Windows におけるマシンランナーのインストール

GitHub から Install-CircleCIRunner.ps1 スクリプトをダウンロードし、アクセスしやすい場所に配置します。
PowerShell を管理者として開き、スクリプトファイルを配置したディレクトリに移動します。

以下を PowerShell で実行します。

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
./Install-CircleCIRunner.ps1

PowerShell インターフェイスにインストール結果が出力されます。

インストール中、マシンランナー (launch-agent-config.yaml) の設定ファイルが Notepad で開かれます。必要な情報をファイルに記入してください ( セルフホストランナーの設定ファイルのリファレンスを参照)。設定ファイルはインストールディレクトリ (デフォルトは C:\Program Files\CircleCI) にあります。

セットアップが完了すると、マシンランナーが自動的に起動し、処理対象のジョブの検索を開始します。

マシンランナーの設定例

セルフホストランナーを使って実行する特定のジョブについて、以下のフィールドを設定する必要があります。

machine: true
resource_class: <namespace>/<resource-class>

以下は、ジョブ設定のシンプルなコード例です。

version: 2.1

workflows:
  build-workflow:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: <namespace>/<resource-class>
    steps:
      - run: echo "Hi I'm on Runners!"

アンインストール・再インストール手順

マシンランナーをアンインストールすると、システムの再インストールの準備をします。

GitHub から Uninstall-CircleCIRunner.ps1 script をダウンロードし、アクセスしやすい場所に配置します。
PowerShell を管理者として開き、スクリプトファイルを配置したディレクトリに移動します。
以下を PowerShell で実行します。
```
./Uninstall-CircleCIRunner.ps1
```

Windows セルフホストランナーの Continuous モードと Single task モード

Windows マシンランナーは、デフォルトでは、セルフホストランナーがジョブの実行に使用する基盤テクノロジーの信頼性を高めるために、 Single task モードで実行されます。 Windows マシンランナーの場合、これが 推奨モード です。

Windows マシンランナーは、continuous モードで実行することも可能ですが、その場合、クリーンなジョブ環境が保証されません。ジョブが期待どおりに実行されず、失敗する可能性があります。

トラブルシューティング

Windows へのマシンランナーのインストールや実行において問題が生じた場合は、セルフホストランナーのトラブルシューティングガイドのマシンランナーのトラブルシューティングのセクションを参照してください。

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site