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

このセクションは、GitLab Runnerの問題を解決する際に役立ちます。

一般的なトラブルシューティングのヒント

ログを表示する

GitLab Runnerサービスはログをsyslogに送信します。ログを表示するには、ディストリビューションのドキュメントを参照してください。ディストリビューションにjournalctlコマンドが含まれている場合は、そのコマンドを使用してログを表示できます:

journalctl --unit=gitlab-runner.service -n 100 --no-pager
docker logs gitlab-runner-container # Docker
kubectl logs gitlab-runner-pod # Kubernetes

サービスを再起動する

systemctl restart gitlab-runner.service

Docker Machineを表示する

sudo docker-machine ls
sudo su - && docker-machine ls

すべてのDocker Machineを削除する

docker-machine rm $(docker-machine ls -q)

config.tomlに変更を適用する

systemctl restart gitlab-runner.service
docker-machine rm $(docker-machine ls -q) # Docker machine
journalctl --unit=gitlab-runner.service -f # Tail the logs to check for potential errors

GitLabおよびGitLab Runnerのバージョンを確認する

GitLabは下位互換性を保証することを目標としています。ただし、最初のトラブルシューティング手順として、GitLab RunnerのバージョンがGitLabのバージョンと同じであることを確認する必要があります。

coordinatorについて

coordinatorは、ジョブのリクエスト元であるGitLabインストールのことです。

つまりRunnerは、coordinator（GitLab APIを介したGitLabインストール）からジョブをリクエストする、分離されたエージェントです。

Windowsでサービスとして実行する場合にログはどこに保存されますか？

• GitLab RunnerがWindowsでサービスとして実行されている場合、システムイベントログが作成されます。これらを表示するには、イベントビューアーを開きます（「ファイル名を指定して実行」メニューでeventvwr.mscと入力するか、「イベントビューアー」を検索します）。次に、Windows Logs > Applicationに移動します。Runnerログのソースはgitlab-runnerです。Windows Server Coreを使用している場合は、PowerShellコマンドget-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -autoを実行して、最後の20件のログエントリを取得します。

デバッグログ生成モードを有効にする

コマンドライン

rootとしてログインしたターミナルから、以下を実行します。

gitlab-runner stop
gitlab-runner --debug run

GitLab Runner config.toml内

デバッグログ生成を有効にするには、config.tomlのグローバルセクションでlog_levelをdebugに設定します。config.tomlの最上部で、concurrent行の前または後に次の行を追加します:

log_level = "debug"

Helmチャート内

GitLab Runner Helmチャートを使用してKubernetesクラスターにGitLab Runnerがインストールされている場合、デバッグログ生成を有効にするには、values.yamlのカスタマイズでlogLevelオプションを設定します:

## Configure the GitLab Runner logging level. Available values are: debug, info, warn, error, fatal, panic
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration/#the-global-section
##
logLevel: debug

Docker executor RunnerのDNSを設定する

Docker executorでGitLab Runnerを設定すると、ホストRunnerデーモンがGitLabにアクセスできてもDockerコンテナがアクセスできない場合があります。これは、ホストでDNSが設定されていても、その設定がコンテナに渡されない場合に発生する可能性があります。

例:

GitLabサービスとGitLab Runnerが、2種類の方法（インターネット経由とVPN経由など）でブリッジされる2つの異なるネットワークに存在しています。Runnerのルーティングメカニズムでは、VPN経由のDNSサービスではなく、デフォルトのインターネットサービスを介してDNSをクエリする可能性があります。この設定を使用すると、次のメッセージが表示されます:

Created fresh repository.
++ echo 'Created fresh repository.'
++ git -c 'http.userAgent=gitlab-runner 16.5.0 linux/amd64' fetch origin +da39a3ee5e6b4b0d3255bfef95601890afd80709:refs/pipelines/435345 +refs/heads/master:refs/remotes/origin/master --depth 50 --prune --quiet
fatal: Authentication failed for 'https://gitlab.example.com/group/example-project.git/'

この場合の認証の失敗の原因は、インターネットとGitLabサービスの間にあるサービスにあります。このサービスは個別の認証情報を使用しており、RunnerがVPN経由でDNSサービスを使用した場合は、Runnerがそれらの認証情報を回避している可能性があります。

使用するDNSサーバーをDockerに指示するには、Runnerのconfig.tomlファイルの[runners.docker]セクションでdns設定を使用します。

dns = ["192.168.xxx.xxx","192.168.xxx.xxx"]

x509: certificate signed by unknown authorityが表示される

詳細については、自己署名証明書を参照してください。

/var/run/docker.sockへアクセスするときにPermission Deniedが表示される

Docker executorを使用する場合に、サーバーにインストールされているDocker Engineに接続しているとします。この場合にはPermission Deniedエラーが表示されることがあります。最も可能性が高い原因は、システムがSELinuxを使用していることです（CentOS、Fedora、RHELではデフォルトで有効になっています）。システムでSELinuxポリシーを調べて、拒否がないか確認してください。

Docker-machineエラー: Unable to query docker version: Cannot connect to the docker engine endpoint.

このエラーはマシンのプロビジョニングに関連しており、次の原因が考えられます:

• TLSエラーが発生している。docker-machineがインストールされている場合、一部の証明書が無効になっている可能性があります。このイシューを解決するには、証明書を削除してRunnerを再起動します:

  sudo su -
  rm -r /root/.docker/machine/certs/*
  service gitlab-runner restart

  再起動したRunnerは、証明書が空であると認識し、証明書を再作成します。

• ホスト名が、プロビジョニングされたマシンでサポートされている長さを超えている。たとえば、UbuntuマシンでのHOST_NAME_MAXの文字数制限は64文字です。ホスト名はdocker-machine lsによって報告されます。Runner設定でMachineNameを確認し、必要に応じてホスト名を短くします。

dialing environment connection: ssh: rejected: connect failed (open failed)

このエラーは、SSH経由で接続をトンネルしているときに、Docker autoscalerがターゲットシステムのDockerデーモンに到達できない場合に発生します。ターゲットシステムにSSHで接続し、docker infoなどのDockerコマンドを正常に実行できることを確認します。

オートスケールされたRunnerにAWSインスタンスプロファイルを追加する

AWS IAMロールを作成した後、IAMコンソールではそのロールにRole ARN（ロールARN）とInstance Profile ARNs（インスタンスプロファイルARN）があります。Role Name（ロール名）not（ではなく）Instance Profile（インスタンスプロファイル）名を使用する必要があります。

[runners.machine]セクションに値"amazonec2-iam-instance-profile=<instance-profile-name>",を追加します。

Javaプロジェクトのビルド時にDocker executorがタイムアウトになる

最も可能性が高い原因は、破損したaufsストレージドライバーです: Javaプロセスがコンテナ内でハングアップします。最適な解決策は、ストレージドライバーをOverlayFSまたはDeviceMapper（低速）のいずれかに変更することです。

Dockerの設定と実行に関する記事 、またはsystemdによる制御と設定に関する記事を確認してください。

アーティファクトのアップロード時に411が表示される

GitLab RunnerがTransfer-Encoding: chunkedを使用していることが原因で発生します。これは、以前のバージョンのNGINXで破損しています（https://serverfault.com/questions/164220/is-there-a-way-to-avoid-nginx-411-content-length-required-errors）。

NGINXを新しいバージョンにアップグレードしてください。詳細については、イシューhttps://gitlab.com/gitlab-org/gitlab-runner/-/issues/1031を参照してください。

他のアーティファクトのアップロードエラーが発生しています。このエラーを詳しくデバッグするにはどうすればよいですか？

アーティファクトは、GitLab Runnerプロセスを回避して、ビルド環境からGitLabインスタンスに直接アップロードされます。次に例を示します:

• Docker executorの場合、アップロードはDockerコンテナから行われます
• Kubernetes executorの場合、アップロードはビルドポッドのビルドコンテナから行われます

ビルド環境からGitLabインスタンスへのネットワークルートは、GitLab RunnerからGitLabインスタンスへのルートとは異なる場合があります。

アーティファクトのアップロードを有効にするには、アップロードパス内のすべてのコンポーネントが、ビルド環境からGitLabインスタンスへのPOSTリクエストを許可していることを確認します。

デフォルトでは、アーティファクトアップローダーはアップロードURLとアップロード応答のHTTPステータスコードをログに記録します。この情報だけでは、どのシステムがエラーを引き起こしたか、またはアーティファクトのアップロードをブロックしたかを理解するには不十分です。アーティファクトのアップロードの問題を解決するには、アップロード応答のヘッダーと本文を確認するために、アップロード試行でデバッグログ生成を有効にします。

アップロードがGitLabに到達してもエラー状態コードで失敗する場合（たとえば、成功以外の応答ステータスコードが生成される場合）は、GitLabインスタンス自体を調べます。一般的なアーティファクトのアップロードのイシューについては、GitLabドキュメントを参照してください。

No URL provided, cache will not be download/uploaded

このエラーは、GitLab Runnerヘルパーが無効なURLを受信するか、リモートキャッシュにアクセスするための事前署名付きURLがない場合に発生します。config.tomlのキャッシュ関連のエントリと、プロバイダー固有のキーと値を確認します。URL構文の要件に従っていないアイテムから無効なURLが作成される可能性があります。

また、ヘルパーimageとhelper_image_flavorが一致し、最新であることを確認してください。

認証情報の設定に問題がある場合は、診断エラーメッセージがGitLab Runnerプロセスログに追加されます。

エラー: warning: You appear to have cloned an empty repository.

HTTP(S)を使用してgit cloneを実行すると（GitLab Runnerを使用するか、テスト用に手動で実行）、次の出力が表示されます:

$ git clone https://git.example.com/user/repo.git

Cloning into 'repo'...
warning: You appear to have cloned an empty repository.

GitLabサーバーのインストールでHTTPプロキシ設定が正しく行われていることを確認してください。独自の設定でHTTPプロキシを使用する場合は、リクエストがGitLab Workhorse socket（GitLab Workhorseソケット）ではなくGitLab Unicorn socket（GitLab Unicornソケット）にプロキシされることを確認してください。

HTTP(S)を介したGitプロトコルはGitLab Workhorseによって解決されるため、これはGitLabのmain entrypoint（メインエントリポイント）です。

Linuxパッケージのインストールを使用しているが、バンドルされているNGINXサーバーを使用したくない場合は、バンドルされていないWebサーバーを使用するを参照してください。

GitLabレシピリポジトリには、ApacheとNGINXのWebサーバー設定の例があります。

ソースからインストールされたGitLabを使用している場合は、上記のドキュメントと例を参照してください。すべてのHTTP(S)トラフィックがGitLab Workhorseを経由していることを確認してください。

ユーザーイシューの例を参照してください。

エラー: TimezoneまたはOffPeakTimezoneの使用時にzoneinfo.zip: no such file or directoryエラーが発生する

[[docker.machine.autoscaling]]の期間が記述されているタイムゾーンを設定できます。この機能は、ほとんどのUnixシステムですぐに動作するはずです。ただし、一部のUnixシステムとほとんどの非Unixシステム（GitLab Runnerバイナリが利用可能なWindowsなど）では、Runnerが起動時に次のエラーでクラッシュする可能性があります:

Failed to load config Invalid OffPeakPeriods value: open /usr/local/go/lib/time/zoneinfo.zip: no such file or directory

このエラーは、Goのtimeパッケージが原因で発生します。GoはIANA Time Zoneデータベースを使用して、指定されたタイムゾーンの設定を読み込みます。ほとんどのUnixシステムでは、このデータベースは、既知のパス（/usr/share/zoneinfo、/usr/share/lib/zoneinfo、/usr/lib/locale/TZ/）のいずれかにすでに存在しています。Goのtimeパッケージは、これら3つのパスすべてでTime Zoneデータベースを検索します。いずれも見つからないが、マシンに設定済みのGo開発環境がある場合は、$GOROOT/lib/time/zoneinfo.zipファイルにフォールバックします。

これらのパスがいずれも存在しない場合（本番環境のWindowsホスト上など）は、上記のエラーがスローされます。

システムがIANA Time Zoneデータベースをサポートしているが、デフォルトでは利用できない場合は、このデータベースをインストールしてみることができます。Linuxシステムでは、次のような方法でこのインストールを実行できます:

# on Debian/Ubuntu based systems
sudo apt-get install tzdata

# on RPM based systems
sudo yum install tzdata

# on Linux Alpine
sudo apk add -U tzdata

システムがこのデータベースを_ネイティブ_な方法で提供していない場合は、次の手順に従ってOffPeakTimezoneを動作させることができます:

1. zoneinfo.zipをダウンロードします。バージョンv9.1.0以降では、タグ付けされたパスからファイルをダウンロードできます。この場合は、zoneinfo.zipダウンロードURLでlatestをタグ名（v9.1.0など）に置き換える必要があります。

2. このファイルを既知のディレクトリに保存します。config.tomlファイルが存在するディレクトリを使用することをお勧めします。たとえば、WindowsマシンでRunnerをホスティングしていて、設定ファイルがC:\gitlab-runner\config.tomlに保存されている場合は、zoneinfo.zipをC:\gitlab-runner\zoneinfo.zipに保存します。

3. zoneinfo.zipファイルのフルパスを含むZONEINFO環境変数を設定します。runコマンドを使用してRunnerを起動する場合は、次のようにします:

   ZONEINFO=/etc/gitlab-runner/zoneinfo.zip gitlab-runner run <other options ...>

   Windowsを使用している場合は次のようにします:

   C:\gitlab-runner> set ZONEINFO=C:\gitlab-runner\zoneinfo.zip
   C:\gitlab-runner> gitlab-runner run <other options ...>

   GitLab Runnerをシステムサービスとして起動する場合は、サービス設定を更新または上書きする必要があります:

   • Unixシステムでは、サービスマネージャーソフトウェアで設定を変更します。
   • Windowsでは、システム設定でGitLab Runnerユーザーが利用できる環境変数のリストにZONEINFO変数を追加します。

複数のGitLab Runnerインスタンスを実行できないのはなぜですか？

同じconfig.tomlファイルを共有していなければ実行できます。

同じ設定ファイルを使用する複数のGitLab Runnerインスタンスを実行すると、デバッグが難しい予期しない動作が発生する可能性があります。一度に1つのGitLab Runnerインスタンスのみが特定のconfig.tomlファイルを使用できます。

ジョブの開始前に遅延が発生する

一部のプロジェクトのジョブで開始前に大幅な遅延が発生し、他のプロジェクトのジョブがすぐに実行される場合、longポーリングの問題が発生している可能性があります。

Symptoms:（症状:）

• ジョブはキューに入れられていますが、実行の開始に異常に長い時間がかかります（通常、GitLabインスタンスのlongポーリングタイムアウトに一致します）。
• 一部のRunnerは停止しているように見えますが、他のRunnerはジョブを正常に処理します。
• GitLab RunnerのログにCONFIGURATION: Long polling issues detectedと表示されます。

Cause:（原因:）

このイシューは、GitLab RunnerワーカーがGitLabへのlongポーリングリクエストで停止し、他のジョブが迅速に処理されるのを妨げる場合に発生します。これらのイシューは、設定に応じて、パフォーマンスのボトルネックから完全なデッドロックまで多岐にわたります。このイシューは、GitLab Workhorse apiCiLongPollingDuration設定（デフォルト）によって制御されるGitLab CI/CD longポーリング機能に関連しています: 50秒）。

Solution:（解決策:）

これらのイシューは、いくつかの設定シナリオで発生する可能性があります。原因、設定例、および解決策に関する包括的な情報については、高度な設定ドキュメントのLongポーリングのイシューセクションを参照してください。

Job failed (system failure): preparing environment:

このエラーは多くの場合、Shellによるプロファイルの読み込みが原因で発生します。スクリプトの1つが失敗の原因となっています。

失敗の原因となることが判明しているdotfilesの例:

• .bash_logout
• .condarc
• .rvmrc

SELinuxもこのエラーの原因となる可能性があります。これは、SELinux監査ログを調べることで確認できます:

sealert -a /var/log/audit/audit.log

RunnerがCleaning upステージの後に突然終了する

「コンテナドリフト検出」設定が有効になっている場合に、ジョブのCleaning up filesステージの後でCrowdStrike Falcon Sensorがポッドを強制終了することが報告されています。ジョブを確実に完了できるようにするには、この設定を無効にする必要があります。

ジョブがremote error: tls: bad certificate (exec.go:71:0s)で失敗する

このエラーは、アーティファクトを作成するジョブの実行中にシステム時刻が大幅に変更された場合に発生する可能性があります。システム時刻が変更されたため、SSL証明書の有効期限が切れ、Runnerがアーティファクトをアップロードしようとするとエラーが発生します。

アーティファクトのアップロード中にSSL検証が確実に成功するようにするには、ジョブの終わりにシステム時刻を有効な日付と時刻に変更します。アーティファクトファイルの作成時刻も変更されているため、アーティファクトファイルは自動的にアーカイブされます。

Helmチャート: ERROR .. Unauthorized

HelmでデプロイされたRunnerをアンインストールまたはアップグレードする前に、GitLabでRunnerを一時停止し、ジョブが完了するまで待ちます。

ジョブの実行中にhelm uninstallまたはhelm upgradeを使用してRunnerポッドを削除すると、ジョブが完了したときに、次のようなUnauthorizedエラーが発生する可能性があります:

ERROR: Error cleaning up pod: Unauthorized
ERROR: Error cleaning up secrets: Unauthorized
ERROR: Job failed (system failure): Unauthorized

これはおそらく、Runnerが削除されるとロールバインドが削除されることが原因で発生します。Runnerポッドはジョブが完了するまで継続し、その後、RunnerがRunnerポッドを削除しようとします。ロールバインドがないと、Runnerポッドはアクセスできなくなります。

詳細については、このイシューを参照してください。

Elasticsearchサービスコンテナの起動エラーmax virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

Elasticsearchには、Elasticsearchが実行されるインスタンスで設定する必要があるvm.max_map_count要求事項があります。

プラットフォームに応じてこの値を正しく設定する方法については、Elasticsearchドキュメントを参照してください。

エラー: Preparing the "docker+machine" executor ERROR: Preparation failed: exit status 1 Will be retried in 3s

このエラーは、Docker Machineがexecutor仮想マシンを正常に作成できない場合に発生する可能性があります。このエラーに関する詳細情報を取得するには、config.tomlで定義したMachineOptionsを使用して、仮想マシンを手動で作成します。

例: docker-machine create --driver=google --google-project=GOOGLE-PROJECT-ID --google-zone=GOOGLE-ZONE ...。

エラー: No unique index found for name

このエラーは、Runnerを作成または更新するときに、データベースにtagsテーブルの一意のインデックスがない場合に発生する可能性があります。GitLab UIでResponse not successful: Received status code 500エラーが発生する場合があります。

このイシューは、長期間にわたって複数のメジャーアップグレードが行われたインスタンスに影響を与える可能性があります。このイシューを解決するには、gitlab:db:deduplicate_tags Rakeタスクを使用して、テーブル内の重複するタグを統合します。詳細については、Rakeタスクを参照してください。