macOSにGitLab Runnerをインストールする

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このページでは、macOS（Apple SiliconおよびIntel x86-64）にGitLab Runnerをインストールする方法を説明します。

GitLab RunnerをインストールするmacOSユーザーは、通常、ローカルまたはリモートで実行されるコンテナまたは仮想マシンにGitLabをインストールします。

ご使用のシステムに対応するバイナリをダウンロードします:
- Intelベースのシステムの場合は次のようにします:
```
sudo curl --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-amd64"
```
- Apple Siliconベースのシステムの場合は次のようにします:
```
sudo curl --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"
```
Bleeding Edge - その他のタグ付きリリースをダウンロードするの説明に従って、利用可能なすべてのバージョンのバイナリをダウンロードできます。
実行のための権限を付与します:
```
sudo chmod +x /usr/local/bin/gitlab-runner
```
GitLab Runnerアプリケーションを実行するユーザーアカウントで、次の手順に従います:
1. Runner設定を登録します。登録プロセスでShell executorを選択します。macOSでiOSアプリケーションまたはmacOSアプリケーションをビルドする場合、ジョブはホスト上で直接実行され、認証済みユーザーのIDを使用します。ジョブはコンテナ内で実行されません。このため、コンテナexecutorを使用する場合よりも安全性が低くなります。詳細については、セキュリティに関する考慮事項のドキュメントを参照してください。
2. ターミナルを開き、現在のユーザーに切り替えます。
```
su - <username>
```
3. GitLab Runnerをサービスとしてインストールして開始します:
```
cd ~
gitlab-runner install
gitlab-runner start
```
これらのコマンドの実行時に発生する可能性のあるエラーの解決方法について詳しくは、トラブルシューティングのセクションを参照してください。
システムを再起動します。

上記の手順に従った場合、GitLab Runnerの設定ファイル（config.toml）は/Users/<username>/.gitlab-runner/にあります。Runnerの設定の詳細について参照してください。

詳細については、用語集を参照してください。

既知の問題

サービスは、現在のユーザーとしてログインしているターミナルウィンドウからインストールする必要があります。このようにインストールした場合にのみ、サービスを管理できます。

現在のユーザーとしてサインインするには、ターミナルでコマンドsu - <username>を実行します。ユーザー名を取得するには、コマンドls /usersを実行します。

macOSでサービスを動作させるための唯一の実証済みの方法は、ユーザーモードでサービスを実行することです。

サービスはユーザーがログインしている場合にのみ実行されるため、macOSマシンで自動ログインを有効にする必要があります。

サービスはLaunchAgentとして起動されます。LaunchAgentsを使用することでビルドはUIインタラクションを実行でき、iOSシミュレーターで実行およびテストできるようになります。

macOSにはLaunchDaemons（バックグラウンドで完全に実行されるサービス）もあることに注意してください。LaunchDaemonsはシステムの起動時に実行されますが、LaunchAgentsと同じUIインタラクションへのアクセス権限はありません。RunnerのサービスをLaunchDaemonとして実行することもできますが、この動作モードはサポートされていません。

installコマンドの実行後に~/Library/LaunchAgents/gitlab-runner.plistファイルを検証することで、GitLab Runnerがサービス設定ファイルを作成したことを確認できます。

Homebrewを使用してgitをインストールした場合、以下を含む/usr/local/etc/gitconfigファイルが追加されている可能性があります:

[credential]
  helper = osxkeychain

これは、ユーザー認証情報をキーチェーンにキャッシュするようにGitに指示しますが、これが必要な動作ではない可能性があります。また、これが原因でフェッチがハングする可能性があります。次のコマンドを使用して、システムのgitconfigからこの行を削除できます:

git config --system --unset credential.helper

または、GitLabユーザーのcredential.helperを無効にすることもできます:

git config --global --add credential.helper ''

次のコマンドを使用して、credential.helperの状態を確認できます:

git config credential.helper

GitLab Runnerをアップグレードする

サービスを停止します:
```
gitlab-runner stop
```
バイナリをダウンロードして、GitLab Runner実行可能ファイルを置き換えます:
- Intelベースのシステムの場合は次のようにします:
```
sudo curl -o /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-amd64"
```
- Apple Siliconベースのシステムの場合は次のようにします:
```
sudo curl -o /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"
```
Bleeding Edge - その他のタグ付きリリースをダウンロードするの説明に従って、利用可能なすべてのバージョンのバイナリをダウンロードできます。
実行のための権限を付与します:
```
sudo chmod +x /usr/local/bin/gitlab-runner
```
サービスを開始します:
```
gitlab-runner start
```

サービスファイルをアップグレードする

LaunchAgent設定をアップグレードするには、サービスをアンインストールしてからインストールする必要があります:

gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

`codesign`をGitLab Runnerサービスで使用する

Homebrewを使用してmacOSにgitlab-runnerをインストールしており、ビルドがcodesignを呼び出すときに、ユーザーキーチェーンにアクセスできるように<key>SessionCreate</key><true/>を設定する必要がある場合があります。GitLabはHomebrewのformulaを保持しないため、公式バイナリを使用してGitLab Runnerをインストールする必要があります。

次の例では、gitlabユーザーとしてビルドを実行し、コード署名のためにそのユーザーがインストールした署名証明書へのアクセスを必要とします:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>SessionCreate</key><true/>
    <key>KeepAlive</key>
    <dict>
      <key>SuccessfulExit</key>
      <false/>
    </dict>
    <key>RunAtLoad</key><true/>
    <key>Disabled</key><false/>
    <key>Label</key>
    <string>com.gitlab.gitlab-runner</string>
    <key>UserName</key>
    <string>gitlab</string>
    <key>GroupName</key>
    <string>staff</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/opt/gitlab-runner/bin/gitlab-runner</string>
      <string>run</string>
      <string>--working-directory</string>
      <string>/Users/gitlab/gitlab-runner</string>
      <string>--config</string>
      <string>/Users/gitlab/gitlab-runner/config.toml</string>
      <string>--service</string>
      <string>gitlab-runner</string>
      <string>--syslog</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
  </dict>
</plist>

macOSのトラブルシューティング

以下のエラーは、macOSでのトラブルシューティングに関連しています。一般的なトラブルシューティングについては、GitLab Runnerのトラブルシューティングを参照してください。

`killed: 9`

Apple Siliconベースのシステムでは、gitlab-runner install、gitlab-runner start、またはgitlab-runner registerコマンドを実行するときにこのエラーが発生する可能性があります。

このエラーを解決するには、~/Library/LaunchAgents/gitlab-runner.plistのStandardOutPathとStandardErrorPathの値で指定されたディレクトリが書き込み可能であることを確認します。

次の例では、/Users/USERNAME/Library/LaunchAgents/gitlab-runner.plistファイルが編集されており、ログファイル用に新しい書き込み可能なディレクトリgitlab-runner-logが含まれています。

 <key>StandardErrorPath</key>
  <string>/Users/USERNAME/gitlab-runner-log/gitlab-runner.err.log</string>
 <key>StandardOutPath</key>
  <string>/Users/USERNAME/gitlab-runner-log/gitlab-runner.out.log</string>
</dict>

エラー: `"launchctl" failed: exit status 112, Could not find domain for`（コンポーネントビルドエラー: specは有効なJSONスキーマである必要があります）

このメッセージは、macOSにGitLab Runnerをインストールしようとしたときに表示される場合があります。SSH接続ではなく、GUIターミナルアプリケーションからGitLab Runnerサービスを管理していることを確認してください。

メッセージ：`Failed to authorize rights (0x1) with status: -60007.`

macOSを使用しているときにGitLab Runnerが上記のメッセージでブロックされた場合、この状況が発生する原因は2つあります:

ユーザーがUIインタラクションを実行できることを確認します:
```
DevToolsSecurity -enable
sudo security authorizationdb remove system.privilege.taskport is-developer
```
1番目のコマンドは、ユーザーのデベロッパーツールへのアクセスを有効にします。2番目のコマンドは、デベロッパーグループのメンバーであるユーザーがUIインタラクションを実行できるようにします（iOSシミュレーターの実行など）。
GitLab RunnerサービスがSessionCreate = trueを使用していないことを確認します。以前は、GitLab Runnerをサービスとして実行するときにSessionCreateを使用してLaunchAgentsを作成していました。その時点（Mavericks）では、これがコード署名を機能させるための唯一の解決策でした。これは最近、OS X El Capitanで変更されました。OS X El Capitanでは、この動作を変更する多くの新しいセキュリティ機能が導入されました。
SessionCreate。ただしアップグレードの場合は、LaunchAgentスクリプトを手動で再インストールする必要があります:
```
gitlab-runner uninstall
gitlab-runner install
gitlab-runner start
```
これで、~/Library/LaunchAgents/gitlab-runner.plistでSessionCreateがfalseに設定されていることを検証できます。

ジョブエラー：`fatal: unable to access 'https://path:3000/user/repo.git/': Failed to connect to path port 3000: Operation timed out`

ジョブの1つがこのエラーで失敗した場合は、RunnerがGitLabインスタンスに接続できることを確認してください。接続は、次のような原因によってブロックされる可能性があります:

ファイアウォール
プロキシ
権限
ルーティング設定

`gitlab-runner start`コマンドでの`FATAL: Failed to start gitlab-runner: exit status 134`

このエラーは、GitLab Runnerサービスが正しくインストールされていないことを示しています。このエラーを解決するには、次のコマンドを実行します:

gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

エラーが解決しない場合は、グラフィカルログインを実行します。グラフィカルログインは、サービスの起動に必要なLaunchAgentをブートストラップします。詳細については、既知の問題を参照してください。

AWSでホストされているmacOSインスタンスは、インスタンスのGUIに接続するために追加の手順を実行する必要があります。ssh -Lオプションを使用してSSHポート転送を有効にし、vncなどのリモートデスクトップクライアントがリモートインスタンスに接続できるようにします。また、AWSでホストされているmacOSインスタンスの/private/etc/ssh/sshd_configでAllowTcpForwarding yesを設定する必要があります。インスタンスを再起動して、sshd設定への変更を適用します。エラーを解決するため、GUIにサインインした後、GUIのターミナルからGitLab Runnerのトラブルシューティングの手順を繰り返し行います。

`gitlab-runner start`コマンドでの`FATAL: Failed to start gitlab-runner: "launchctl" failed with stderr: Load failed: 5: Input/output error`

gitlab-runner startコマンドの実行時にこのエラーが発生した場合は、~/Library/LaunchAgents/gitlab-runner.plistのStandardOutPathとStandardErrorPathの値として指定されたディレクトリが存在することを確認してください:

<key>StandardOutPath</key>
<string>/usr/local/var/log/gitlab-runner.out.log</string>
<key>StandardErrorPath</key>
<string>/usr/local/var/log/gitlab-runner.err.log</string>

ディレクトリが存在しない場合はディレクトリを作成し、それらに対する読み取りおよび書き込みを行うための適切な権限がRunnerサービスユーザーにあることを確認します。

エラー: `Error on fetching TLS Data from API response... error error=couldn't build CA Chain`（コンポーネントビルドエラー: specは有効なJSONスキーマである必要があります）

GitLab Runner v15.5.0以降にアップグレードすると、次のエラーが発生することがあります:

Certificate doesn't provide parent URL: exiting the loop  Issuer=Baltimore CyberTrust Root IssuerCertURL=[] Serial=33554617 Subject=Baltimore CyberTrust Root context=certificate-chain-build
Verifying last certificate to find the final root certificate  Issuer=Baltimore CyberTrust Root IssuerCertURL=[] Serial=33554617 Subject=Baltimore CyberTrust Root context=certificate-chain-build
ERROR: Error on fetching TLS Data from API response... error  error=couldn't build CA Chain: error while fetching certificates from TLS ConnectionState: error while fetching certificates into the CA Chain: couldn't resolve certificates chain from the leaf certificate: error while resolving certificates chain with verification: error while verifying last certificate from the chain: x509: “Baltimore CyberTrust Root” certificate is not permitted for this usage runner=x7kDEc9Q

このエラーが発生した場合は、次の操作を行う必要があります:

GitLab Runner v15.5.1以降にアップグレードします。
[runners.feature_flags]設定でFF_RESOLVE_FULL_TLS_CHAINをfalseに設定します。次に例を示します:

[[runners]]
  name = "example-runner"
  url = "https://gitlab.com/"
  token = "TOKEN"
  executor = "docker"
  [runners.feature_flags]
    FF_RESOLVE_FULL_TLS_CHAIN = false

この機能フラグを無効にすると、SHA-1署名またはその他の非推奨のルート証明書署名を使用するHTTPSエンドポイントのTLS接続の問題を修正できる場合があります。

macOSにGitLab Runnerをインストールする

既知の問題

GitLab Runnerをアップグレードする

サービスファイルをアップグレードする

codesignをGitLab Runnerサービスで使用する

macOSのトラブルシューティング

killed: 9

エラー: "launchctl" failed: exit status 112, Could not find domain for（コンポーネントビルドエラー: specは有効なJSONスキーマである必要があります）

メッセージ：Failed to authorize rights (0x1) with status: -60007.

ジョブエラー：fatal: unable to access 'https://path:3000/user/repo.git/': Failed to connect to path port 3000: Operation timed out

gitlab-runner startコマンドでのFATAL: Failed to start gitlab-runner: exit status 134

gitlab-runner startコマンドでのFATAL: Failed to start gitlab-runner: "launchctl" failed with stderr: Load failed: 5: Input/output error

エラー: Error on fetching TLS Data from API response... error error=couldn't build CA Chain（コンポーネントビルドエラー: specは有効なJSONスキーマである必要があります）