Windows 用のランナーをセットアップする
Windows Runner によって、ユーザー自身の Windows インフラストラクチャ上の Pipelines でビルドを実行できます。セルフホスト Windows Runner で使用するビルド時間に対して課金されなくなります。
前提条件
OpenJDK 11 (11.0.15 以上) をインストール済み
Git 2.35.0 以上
PowerShell 5.0 以降
ランナーのホストとして 8GB 以上の RAM を搭載した 64 ビットの Windows 10 以降または Windows Server 2019以降のインスタンス。
Disable the Windows pagefile and swapfile (optional, recommended)
Below are the sample chocolatey scripts to install all of the prerequisites required:
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ビルド時間を短縮するために、nuget、xUnit、nUnit など、Pipelines が必要とするその他の依存関係を事前にインストールすることをお勧めします。
未署名のスクリプトを PowerShell で実行することを許可する
Windows ランナーは、リポジトリをクローンしてパイプラインの各stepでscriptを実行するための PowerShell スクリプトを生成します。これらのスクリプトはパイプラインの実行時に生成されて、デジタル署名されません。
To allow the Windows runners to run unsigned PowerShell scripts, set the PowerShell execution policy of the CurrentUser to either:
RemoteSigned(推奨)unrestrictedbypass
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.
CurrentUser の実行ポリシーを確認するには、次の手順に従います。
Windows の [スタート] メニューから Windows PowerShell を開きます。
次のコマンドを実行すると、
CurrentUserの実行ポリシーが返されます。Get-ExecutionPolicy -Scope CurrentUser
CurrentUser の実行ポリシーを RemoteSigned に変更するには、次の手順に従います。
Windows PowerShell で、次のコマンドを実行します。
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserGet-ExecutionPolicyを実行して正常に変更されたことを検証し、CurrentUserにRemoteSigned実行ポリシーがあることを確認します。Get-ExecutionPolicy -Scope CurrentUser
For information on Microsoft PowerShell execution policies, visit Microsoft Docs — PowerShell: about Execution Policies.
Windows ページファイルとスワップファイルを無効にする
べスト プラクティス
Windows Runner を作成する前に、ご利用の Windows 環境で swapfile.sys と pagefile.sys を無効にすることを強くお勧めします。スワップを有効にすると、メモリと OOM に関して決定的でないビルドが生じる可能性があります。つまり、十分なスワップが利用可能であればビルドが成功しますが、十分なスワップが利用不可であれば同じビルドで OOM が生じる可能性があります。
Windows 10 で pagefile.sys と swapfile.sys を無効にするには、次の手順に従います。次の手順がうまくいかない場合は、ディストリビューションのドキュメントをご参照のうえ、ご利用の Windows 環境を構成してください。
Windows で、[スタート] を選択して [スタート] メニューに「システムの詳細設定」と入力し、Enter キーを押して開きます。
[詳細設定] タブを選択して、[システムのプロパティ] ダイアログの [パフォーマンス] セクションにある [設定] ボタンをクリックします。
[詳細設定] タブを選択して、[パフォーマンス オプション] ダイアログの [仮想メモリ] セクションにある [変更] ボタンをクリックします。
[仮想メモリ] ダイアログの [各ドライブのページ ファイル サイズ] セクションで [すべてのドライブのページング ファイル サイズを自動で管理] を選択解除し、[ページング ファイルなし] > [設定] ボタンの順に選択します。
[OK] を選択して、システムを再起動します。
ランナーの使用
1 台のマシンに複数のランナーをデプロイすると、共有ビルド環境が原因で、リソースの共有や使用量の競合に関連する問題が発生する可能性があります。
ランナー ページに移動します。
For Workspace runners, visit Workspace settings, then Workspace runners.
For Repository runners, visit Repository settings, then Runners.
[ランナーを追加] を選択します。
[ランナー インストール] ダイアログの [システムとアーキテクチャ] で [Windows (64bit)] を選択します。
[Runner のインストール] ダイアログの Run ステップに表示された zip ファイルをダウンロードします。
ファイルを任意のディレクトリに解凍します。次に例を示します。
C:\Users\your_user_name\atlassian_runners管理者として PowerShell を開いて Runner フォルダーの下の
binディレクトリに移動し、[Runner のインストール] ダイアログの [実行] ステップに記載されたコマンドを実行します。
Windows ランナーは PowerShell を使用して、パイプライン ステップを Windows マシン (ホスト デバイス) で実行します。これによってランナーはアプリをホストで実行できますが、クリーンなビルド環境が全ステップで提供されるわけではありません。ステップによって発生する副作用 (アプリのインストール、データベース サービスの開始、ビルド ディレクトリ外部におけるファイルの編集など) は、(新しいパイプラインの実行を含む) 次に実行するステップに影響を与える可能性があります。これを補うために、ランナーは各ステップの後にビルド ディレクトリを空にしようとします。各ステップで実行するスクリプトが他のステップに大きな影響を与えないようにするのは、ユーザーの責任です。
パイプラインのリファレンス変数
変数は、ビルド コンテナーの環境変数として設定されています。bitbucket-pipelines.yml ファイルか、次のように参照して呼び出す任意のスクリプトから変数にアクセスできます。ここで、AWS_SECRET は変数の名前です。
$env:AWS_SECRETWindows Runner の制限事項
共有ビルド環境
ランナーはシェルによってステップ スクリプトを実行するので、ホスト マシンはランナーで実行するようにスケジュールされた複数のステップによって共有されます。スクリプトのインストール、または新しいライブラリのインストールなど、システム全体の変更がステップ内のランナーに加えられた場合、その変更はホスト マシンで実行される後続のすべてのステップに影響します。
サポートされない機能
次の機能は実装方法に制限があってセキュリティが複雑なため、セルフホスト ランナーではサポート対象外です。
Step size — There is no restriction on memory usage for runners.
Windows ランナーは PowerShell で直接実行されるため、これらの機能のほとんどはサポートされていません。つまり、Docker コンテナーは関与しません。
制限と回避策
キャッシュ
Pre-defined Docker cache is not supported — Docker and the Pipelines pre-defined Docker cache are not supported for Windows Runners.
キャッシュを異なる OS 間で共有する — Windows ランナーや Linux ランナーなど、異なるキャッシュ名をランナー タイプごとに指定することをお勧めします。次に例を示します。
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 専用に生成されたファイルを使用しようとした際など、エラーが発生する可能性があります。
Bloated cache folder: Due to performance implications, we do not clean up the cache folder at the end of step execution. This may lead to the size of cache directories increasing rapidly, particularly for a workspace runner. If this occurs, we recommend creating a scheduled task to clean up cache folders on a regular basis. For information on creating scheduled tasks in PowerShell, visit Microsoft Docs — PowerShell New-ScheduledTask.
キャッシュ フォルダーの場所は制限されていないため、キャッシュは、
c:\windowsを含めてデバイスの任意のディレクトリに保存できます。キャッシュを定義する場所の技術的な影響にご留意のうえ、ホスト マシンが復旧可能であることをご確認ください。
テスト レポート
There is some additional setup required for .Net test reporting, refer to the following support document for details: Get started with tests in Pipelines
Git LFS
In order to use Git LFS, you need to install Git LFS on your hosted machine. If you use chocolatey, you can install Git LFS with the following PowerShell commands:
choco install git-lfs.install
git lfs install条件付きステップ
The glob path defined in the step condition can only support a forward slash (/) and not a backslash (\) even if the step runs on Windows. So it would look like the example provided below:
- 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 などのツールによってビルドする場合
For security reasons, a runner will not add your SSH keys to the build environment automatically. If required, SSH keys can be passed to a runner using a secure variable.
非公開キーをリポジトリ変数として受け渡す場合、次のようなセキュリティ上のリスクがあります。
パイプライン ビルドが子プロセスを生成する場合は、リポジトリ変数がその子プロセスにコピーされる。
セキュアな環境変数は、リポジトリへの書き込みアクセスを持つすべてのユーザーが取得できる。
We recommend that you never reuse an SSH key as a repository variable. Generate a new SSH key-pair for Pipelines, so the key can be disabled if it is compromised. It is possible to use deployment variables, which you can use with deployment permissions to control access. For details, see: Variables and secrets — Deployment variables.
セキュアなリポジトリ変数を OpenSSH で使用して SSH キーを追加するには、次の手順に従います。
以下のような OpenSSH をインストールします。
choco install opensshPowerShell で次のような新しい SSH キーを生成します。
ssh-keygen -t rsa -b 4096 -N '' -f ~/.ssh/my_ssh_key非公開キーを base64 にエンコードします。現在、Pipelines では環境変数の改行はサポートされていません。次に例を示します。
[convert]::ToBase64String((Get-Content -path "~/.ssh/my_ssh_key" -Encoding byte))エンコードされたキーを保護された変数として追加します。エンコードされたキーを PowerShell からコピーして、次のようにセキュアな Bitbucket Pipelines 環境変数としてリポジトリに追加します。
Bitbucket のリポジトリで、[リポジトリ設定] > [リポジトリ変数] の順に選択します。
PowerShell から、base64 エンコード済みの非公開キーをコピーします。
エンコード済みのキーを環境変数の値としてペーストします。[セキュア] が選択されていることを確認します。
公開キーをリモート ホストにインストールします。Pipelines がそのホストを認証できるようになる前に、リモート ホストに公開キーをインストールする必要があります。Pipelines ビルドに他の Bitbucket リポジトリに対するアクセス権を付与する場合は、公開キーをそのリポジトリに追加する必要があります。
SSH によってリモート ホストに公開キーをコピーするには、
ssh-copy-idコマンドを使用します。このコマンドは、キーをリモート ホスト上の~/.ssh/authorized_keysファイルに追加します。ssh-copy-id -i my_ssh_key <username>@<remote_host><username>はリモート ホスト上のユーザーです。サーバーへの SSH アクセスをテストするには、次の手順に従います。
ssh -i ~/.ssh/my_ssh_key user@hostホスト キーを取得して、ホスト VM (仮想マシン) の
~/.ssh/known_hostsファイルに追加します。known_hostsファイルには、ユーザーがアクセスする SSH サーバーの DSA ホスト キーが格納されます。適切なリモート ホストに接続していることを確認することが重要です。任意のリモート サーバーの DSA ホスト キーを取得します。これを行うには、次のコマンドを実行します。
ssh-keyscan -t rsa server.example.comこれらのキーをホスト仮想マシンの
~/.ssh/known_hostsファイルに追加します。無関係な行はすべて削除できます。
SSH キーを
bitbucket-pipelines.ymlファイルに追加してデコードします。次に例を示します。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 キーペアを定期的に更新することをお勧めします。
この内容はお役に立ちましたか?