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

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

前提条件

  • OpenJDK 11 (11.0.11 以上) をインストール済み

  • Git 2.35.0 以上

  • ランナー用のホストとして少なくとも 8GB の RAM を搭載した 64 ビット MacOS インスタンス。

ランナーの使用

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

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

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

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

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

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

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

  5. Untar the file to the desired directory, for example: /Users/your_user_name/atlassian_runner

  6. Open Terminal (or shell of your choice), go to the bin directory under your Runner folder, run the command provided in Run step on the Runner installation dialog.

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


MacOS ランナーの制限事項

ランナーが使用したメモリ

スワップ メモリは完全には無効にできないため、ランナーで実行されるステップによって作成されたプロセスはスワップ メモリを使用する可能性があります。これによって、メモリ使用量エラーと OOM (メモリ不足) エラーに関する暫定的なビルド結果が生じる可能性があります。これは、利用可能なスワップ メモリが十分にあってビルドが成功する場合もあれば、十分なスワップができずに同じビルドがメモリ不足になる場合があります。この制限によるメモリの問題がないかを必ずご確認ください。

共有ビルド環境

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

サポートされない機能

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

その他の制限と回避策

キャッシュ

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

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

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 pipelines: custom: customPipelineWithRunnerAndCache: - step: name: Step 1 runs-on: - 'macos' script: - echo "This step will run on a self hosted runner."; caches: - macos_bundler - step: name: Step 2 script: - echo "This step will run on Atlassian's infrastructure as usual."; caches: - linux_bundler definitions: caches: linux_bundler: vendor/bundle macos_bundler: vendor/bundle

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

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

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

Git LFS

Git LFS を使用するには、Git LFS をホストされたマシンにインストールする必要があります。Homebrew を使用している場合は、次のターミナル コマンドで Git LFS をインストールできます。

1 brew install git-lfs

 

SSH キー

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

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

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

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

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

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

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

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

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

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

  1. ターミナルで次のような新しい SSH キーを生成します。

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

    1 base64 -w 0 ~/.ssh/my_ssh_key
  3. エンコードされたキーを保護された変数として追加します。暗号化されたキーをターミナルからコピーして、次のようにセキュアな Bitbucket Pipelines 環境変数としてリポジトリに追加します。

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

    2. ターミナルで、base64 エンコード済みの非公開キーをコピーします。

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

  4. 公開キーをリモート ホストにインストールします。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
  5. ホスト キーを取得して、ホスト 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.

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

    1 2 3 4 5 6 7 pipelines: default: - step: runs-on: self.hosted script: - (umask 077 ; echo $MY_SSH_KEY | base64 --decode > ./id_rsa) - ssh -i ./id_rsa <user>@<host> 'echo "connected to `host` as $USER"'

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

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

 

その他のヘルプ