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

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

前提条件

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

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

ビルド時間を短縮するために、nugetxUnitnUnit など、Pipelines が必要とするその他の依存関係を事前にインストールすることをお勧めします。

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

Windows ランナーは、リポジトリをクローンしてパイプラインの各stepscriptを実行するための PowerShell スクリプトを生成します。これらのスクリプトはパイプラインの実行時に生成されて、デジタル署名されません。

Windows ランナーが未署名の PowerShell スクリプトを実行できるようにするには、CurrentUserPowerShell 実行ポリシーを次のいずれかに設定します。

  • RemoteSigned (推奨)

  • unrestricted

  • bypass

RemoteSigned 実行ポリシーでは、ローカルの未署名 (未認定) スクリプトをデバイスで実行できます。これには、潜在的に悪意のある未署名のスクリプトが含まれます。実行ポリシーの変更前に、実行ポリシーをレビューしてMicrosoft Docs - PowerShell 実行ポリシーでセキュリティへの影響をご検討ください。

CurrentUser の実行ポリシーを確認するには、次の手順に従います。

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

  2. 次のコマンドを実行すると、CurrentUser の実行ポリシーが返されます。

    1 Get-ExecutionPolicy -Scope CurrentUser

CurrentUser の実行ポリシーを RemoteSigned に変更するには、次の手順に従います。

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

    1 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  2. Get-ExecutionPolicy を実行して正常に変更されたことを検証し、CurrentUserRemoteSigned 実行ポリシーがあることを確認します。

    1 Get-ExecutionPolicy -Scope CurrentUser

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

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

べスト プラクティス

Windows Runner を作成する前に、ご利用の Windows 環境で swapfile.syspagefile.sys を無効にすることを強くお勧めします。スワップを有効にすると、メモリと OOM に関して決定的でないビルドが生じる可能性があります。つまり、十分なスワップが利用可能であればビルドが成功しますが、十分なスワップが利用不可であれば同じビルドで OOM が生じる可能性があります。

Windows 10 で pagefile.sysswapfile.sys を無効にするには、次の手順に従います。次の手順がうまくいかない場合は、ディストリビューションのドキュメントをご参照のうえ、ご利用の Windows 環境を構成してください。

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

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

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

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

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

ランナーの使用

1 台のマシンに複数のランナーをデプロイすると、共有ビルド環境が原因で、リソースの共有や使用量の競合に関連する問題が発生する可能性があります。

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

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

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

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

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

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

  5. ファイルを任意のディレクトリに解凍します。次に例を示します。C:\Users\your_user_name\atlassian_runners

  6. 管理者として PowerShell を開いて Runner フォルダーの下の bin ディレクトリに移動し、[Runner のインストール] ダイアログの Run ステップに記載されたコマンドを実行します。

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. これらのキーをホスト仮想マシンの ~/.ssh/known_hosts ファイルに追加します。無関係な行はすべて削除できます。

  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))) | Out-File -Encoding "ASCII" id_rsa - ssh -T -i ./id_rsa git@bitbucket.org

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

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

その他のヘルプ