Windows 用のランナーをセットアップする

Windows Runner によって、ユーザー自身の Windows インフラストラクチャ上の Pipelines でビルドを実行できます。セルフホスト Windows Runner で使用するビルド時間に対して課金されなくなります。

前提条件

すべての必要な前提条件をインストールするための chocolatey スクリプトの例を以下に示します。

1 2 3 4 choco install -y git choco install -y openjdk11 choco install -y dotnetfx --pre choco install git-lfs.install # if you need to use git-lfs features

To improve build times, we recommend installing any other dependencies your Pipelines require in advance, such as nuget, xUnit, nUnit, etc.

未署名のスクリプトを PowerShell で実行することを許可する

The Windows runner generates PowerShell scripts for cloning the repository and running the script for each step in the pipeline. These scripts are generated when the pipeline is run, preventing them from being digitally signed.

To allow the Windows runners to run unsigned PowerShell scripts, set the PowerShell execution policy of the CurrentUser to either:

  • RemoteSigned (recommended)

  • unrestricted

  • bypass

The RemoteSigned execution policy allows local unsigned (uncertified) scripts to run on the device. This includes any potentially malicious unsigned scripts. Before changing the execution policy, review the execution policies and consider their security implications at Microsoft Docs — PowerShell execution policies.

To check the execution policy for the CurrentUser:

  1. Windows の [スタート] メニューから Windows PowerShell を開きます。

  2. Run the following command, which will return the execution policy for the CurrentUser:

    1 Get-ExecutionPolicy -Scope CurrentUser

To change the execution policy for CurrentUser to RemoteSigned:

  1. Windows PowerShell で、次のコマンドを実行します。

    1 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  2. Verify that the change was successful by running Get-ExecutionPolicy and confirm that the CurrentUser has the RemoteSigned execution policy.

    1 Get-ExecutionPolicy -Scope CurrentUser

Microsoft PowerShell 実行ポリシーの詳細については「Microsoft Docs - PowerShell: 実行ポリシーについて」をご参照ください

Windows ページファイルとスワップファイルを無効にする

べスト プラクティス

Before you create a Windows Runner, we strongly recommend disabling swapfile.sys and pagefile.sys in your Windows environment. Having swap enabled can lead to non-deterministic build results in regards to memory and OOMing, meaning that sometimes enough swap is available and a build may pass, while other times not enough swap is available which could make the same build OOM.

Follow the steps below to disable pagefile.sys and swapfile.sys in Windows 10. If the following instructions do not work, consult your distributions documentation to configure your Windows environment:

  1. Windows で、[スタート] を選択して [スタート] メニューに「システムの詳細設定」と入力し、Enter キーを押して開きます。

  2. [詳細設定] タブを選択して、[システムのプロパティ] ダイアログの [パフォーマンス] セクションにある [設定] ボタンをクリックします。

  3. [詳細設定] タブを選択して、[パフォーマンス オプション] ダイアログの [仮想メモリ] セクションにある [変更] ボタンをクリックします。

  4. [仮想メモリ] ダイアログの [各ドライブのページ ファイル サイズ] セクションで [すべてのドライブのページング ファイル サイズを自動で管理] を選択解除し、[ページング ファイルなし] > [設定] ボタンの順に選択します。

  5. [OK] を選択して、システムを再起動します。

ランナーの使用

現在、ホスト マシンごとに 1 つのランナーの実行のみがサポートされています。

  1. ランナー ページに移動します。

    • ワークスペース ランナーについては、[ワークスペース設定] > [ワークスペース ランナー] の順に移動してご確認ください。

    • リポジトリ ランナーについては、[リポジトリ設定] > [ランナー] の順に移動してご確認ください。

  2. [ランナーを追加] を選択します。

  3. [ランナー インストール] ダイアログの [システムとアーキテクチャ] で [Windows (64bit)] を選択します。

  4. [Runner のインストール] ダイアログの Run ステップに表示された zip ファイルをダウンロードします。

  5. Unzip the zip file to the desired directory, for example: C:\Users\your_user_name\atlassian_runners

  6. Open PowerShell as an administrator, go to the bin directory under your Runner folder, run the command provided in Run step on the Runner installation dialog.

Windows ランナーは PowerShell を使用して、パイプライン ステップを Windows マシン (ホスト デバイス) で実行します。これによってランナーはアプリをホストで実行できますが、クリーンなビルド環境が全ステップで提供されるわけではありません。ステップによって発生する副作用 (アプリのインストール、データベース サービスの開始、ビルド ディレクトリ外部におけるファイルの編集など) は、(新しいパイプラインの実行を含む) 次に実行するステップに影響を与える可能性があります。これを補うために、ランナーは各ステップの後にビルド ディレクトリを空にしようとします。各ステップで実行するスクリプトが他のステップに大きな影響を与えないようにするのは、ユーザーの責任です。


Windows Runner の制限事項

共有ビルド環境

ランナーはシェルによってステップ スクリプトを実行するので、ホスト マシンはランナーで実行するようにスケジュールされた複数のステップによって共有されます。スクリプトのインストール、または新しいライブラリのインストールなど、システム全体の変更がステップ内のランナーに加えられた場合、その変更はホスト マシンで実行される後続のすべてのステップに影響します。

サポートされない機能

次の機能は実装方法に制限があってセキュリティが複雑なため、セルフホスト ランナーではサポート対象外です。

制限と回避策

キャッシュ

  • 事前定義された Docker キャッシュはサポート対象外 — Docker と Pipelines の事前定義済み Docker キャッシュは、Windows ランナーでサポートされていません。

  • キャッシュを異なる OS 間で共有する — Windows ランナーや Linux ランナーなど、異なるキャッシュ名をランナー タイプごとに指定することをお勧めします。次に例を示します。

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 pipelines: custom: customPipelineWithRunnerAndCache: - step: name: Step 1 runs-on: - 'windows' script: - echo "This step will run on a self hosted windows infrastructure."; caches: - windows_bundler - step: name: Step 2 runs-on: - 'linux' script: - echo "This step will run on a self hosted linux infrastructure."; caches: - linux_bundler - step: name: Step 3 runs-on: - 'linux' script: - echo "This step will run on Atlassian's infrastructure as usual."; caches: - linux_bundler definitions: caches: linux_bundler: vendor/bundle windows_bundler: vendor/bundle

    キャッシュには、他のオペレーティング システムでは動作しないプラットフォーム固有のファイルを含められます。キャッシュを異なるオペレーティング システム間で共有すると、Windows ランナーが Linux 専用に生成されたファイルを使用しようとした際など、エラーが発生する可能性があります。

  • 肥大化したキャッシュ フォルダー: パフォーマンスに影響することから、ステップ実行の最後にキャッシュ フォルダーをクリーン アップしません。このため、特にワークスペース ランナーでキャッシュ ディレクトリのサイズが急速に増加する可能性があります。この場合は、キャッシュ フォルダーを定期的にクリーン アップするスケジュールされたタスクを作成することをお勧めします。PowerShell でのスケジュールされたタスクの作成方法については、Microsoft によるドキュメント—「PowerShell New-ScheduledTask cmdlet」をご参照ください。

  • キャッシュ フォルダーの場所は制限されていないため、キャッシュは、c:\windows を含めてデバイスの任意のディレクトリに保存できます。キャッシュを定義する場所の技術的な影響にご留意のうえ、ホスト マシンが復旧可能であることをご確認ください。

テスト レポート

.Net テスト レポートには、いくつかの追加セットアップが必要です。詳細についてはサポート ドキュメント「Pipelines のテスト レポート」をご参照ください

Git LFS

Git LFS を使用するには、ホストされたマシンに Git LFS をインストールする必要があります。chocolatey を使用する場合は、次の PowerShell コマンドで Git LFS をセットアップできます。

1 2 choco install git-lfs.install git lfs install

条件付きステップ

ステップ条件で定義された glob パスは、Windows でステップが実行されている場合でも、スラッシュ (/) のみをサポートしてバックスラッシュ (\) はサポートしません。したがって、以下の例のようになります。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 - step: name: step1 runs-on: - self.hosted - windows script: - echo "failing paths" - exit 1 condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**"

SSH キー

次のような場合、Bitbucket Pipelines で SSH キーをセットアップすることができます。

  • ビルドで Bitbucket やその他のホスティング サービスとの認証を行い、非公開の依存関係を取得する必要があります。

  • デプロイで成果物をアップロードする前にリモート ホストまたはサービスとの認証を行う必要があります。

  • SSH、SFTP、または SCP などのツールによってビルドする場合

セキュリティ上の理由から、ランナーは SSH キーをビルド環境に自動で追加しません。必要な場合は、保護された変数によって SSH キーをランナーに渡せます。

非公開キーをリポジトリ変数として受け渡す場合、次のようなセキュリティ上のリスクがあります。

  • パイプライン ビルドが子プロセスを生成する場合は、リポジトリ変数がその子プロセスにコピーされる。

  • セキュアな環境変数は、リポジトリへの書き込みアクセスを持つすべてのユーザーが取得できる。

SSH キーをリポジトリ変数として絶対に再利用しないことをお勧めします。Pipelines 用の新しい SSH キーペアを生成して、侵害された場合にキーを無効にできるようにします。デプロイ権限と併用できるデプロイ変数によって、アクセスを制御できます。詳細は「変数とシークレット - デプロイ変数」をご参照ください。

セキュアなリポジトリ変数を OpenSSH で使用して SSH キーを追加するには、次の手順に従います。

  1. 以下のような OpenSSH をインストールします。

    1 choco install openssh
  2. PowerShell で次のような新しい SSH キーを生成します。

    1 ssh-keygen -t rsa -b 4096 -N '' -f ~/.ssh/my_ssh_key
  3. 非公開キーを base64 にエンコードします。現在、Pipelines では環境変数の改行はサポートされていません。次に例を示します。

    1 [convert]::ToBase64String((Get-Content -path "~/.ssh/my_ssh_key" -Encoding byte))
  4. エンコードされたキーを保護された変数として追加します。エンコードされたキーを PowerShell からコピーして、次のようにセキュアな Bitbucket Pipelines 環境変数としてリポジトリに追加します。

    1. Bitbucket のリポジトリで、[リポジトリ設定] > [リポジトリ変数] の順に選択します。

    2. PowerShell から、base64 エンコード済みの非公開キーをコピーします。

    3. エンコード済みのキーを環境変数の値としてペーストします。[セキュア] が選択されていることを確認します。

  5. 公開キーをリモート ホストにインストールします。Pipelines がそのホストを認証できるようになる前に、リモート ホストに公開キーをインストールする必要があります。Pipelines ビルドに他の Bitbucket リポジトリに対するアクセス権を付与する場合は、公開キーをそのリポジトリに追加する必要があります。

    SSH によってリモート ホストに公開キーをコピーするには、ssh-copy-id コマンドを使用します。このコマンドは、キーをリモート ホスト上の ~/.ssh/authorized_keys ファイルに追加します。

    1 ssh-copy-id -i my_ssh_key <username>@<remote_host>

    <username> はリモート ホスト上のユーザーです。

    サーバーへの SSH アクセスをテストするには、次の手順に従います。

    1 ssh -i ~/.ssh/my_ssh_key user@host
  6. ホスト キーを取得して、ホスト VM (仮想マシン) の ~/.ssh/known_hosts ファイルに追加します。
    known_hosts ファイルには、ユーザーがアクセスする SSH サーバーの DSA ホスト キーが格納されます。適切なリモート ホストに接続していることを確認することが重要です。

    1. 任意のリモート サーバーの DSA ホスト キーを取得します。これを行うには、次のコマンドを実行します。

      1 ssh-keyscan -t rsa server.example.com
    2. Add those keys to the ~/.ssh/known_hosts file in the host VM. You can remove any unrelated lines.

  7. SSH キーを bitbucket-pipelines.yml ファイルに追加してデコードします。次に例を示します。

    1 2 3 4 5 6 7 8 9 pipelines: default: - step: runs-on: - self.hosted - windows script: - [Text.Encoding]::ASCII.GetString([Convert]::FromBase64String($Env:MY_SSH_KEY)) > ./id_rsa - ssh -i ./id_rsa <user>@<host> 'echo "connected from pipelines"'

上記のスクリプトでは、~/.ssh/another_private_key ではなく ./id_rsa を代用します。これによって、ランナーはランナーのビルド フォルダーに生成されたファイルを監視して、ステップの最後にそのファイルの削除を試みます。ランナーのビルド フォルダー外に作成されたファイルは削除されず、ランナーは非公開キーを ~/.ssh に残すので、この場合はキーが悪用される可能性が高くなります。

ビルド フォルダーをクリーン アップできない可能性はまだあります。いかなるデータが侵害される可能性も減らすため、このステップで用いた SSH キーペアを定期的に更新することをお勧めします。

その他のヘルプ