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

このセクションでは GitLab Runner のトラブルシューティングについて説明します。

note
クリティカルセキュリティリリースでは、グループとプロジェクトの Runner 登録トークンがリセットされます。自動化されたプロセス（登録トークンの値をエンコードするスクリプト）を使用してランナーを登録している場合、このアップデートによってそのプロセスが壊れます。ただし、以前に登録したランナーには影響はありません。

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

ログを見る

  • tail -100 /var/log/syslog (Debian)
  • tail -100 /var/log/messages (RHEL)
  • docker logs gitlab-runner-container (Docker)
  • kubectl logs gitlab-runner-pod (Kubernetes)

サービスを再起動します：

  • service gitlab-runner restart

Dockerマシンを表示します：

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

すべてのDocker Machineを削除します：

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

config.toml に変更を加えた後、すべてのDockerマシンを削除してください：

  • service gitlab-runner restart
  • docker-machine rm $(docker-machine ls -q)
  • tail -f /var/log/syslog (Debian)
  • tail -f /var/log/messages (RHEL)

GitLabとGitLab Runnerのバージョンを確認します。

GitLabは後方互換性を保証することを目指しています。しかし、トラブルシューティングの最初のステップとして、GitLab RunnerのバージョンがGitLabのバージョンと同じであることを確認してください。

coordinator とはどういう意味ですか？

coordinator は、ジョブがリクエストされる GitLab インストールです。

言い換えると、Runnerはcoordinator （GitLab APIを通したGitLabインストール）からジョブをリクエストする内部エージェントです。

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

  • GitLab RunnerがWindows上でサービスとして実行されている場合、システムのイベントログが作成されます。イベントログを見るには、イベントビューアーを開いてください（ファイル名を指定して実行メニューからeventvwr.msc と入力するか、”Event Viewer “と検索してください）。そして、Windowsログ > アプリケーションと進んでください。Runner ログのソースは gitlab-runner です。 Windows Server Core を使用している場合は、この PowerShell コマンドを実行し、直近の 20 個のログエントリを取得します：get-eventlog Application -Source gitlab-runner -Newest 20 | format-table -wrap -auto。

デバッグログモードの有効化

caution
デバッグロギングは深刻なセキュリティリスクになる可能性があります。出力はジョブが利用できるすべての変数と他のシークレットの内容を含みます。

コマンドラインで

ターミナルからrootでログインして実行します：

gitlab-runner stop
gitlab-runner --debug run

GitLabランナーでconfig.toml

log_level の設定をdebugにすることで、config.toml](../configuration/advanced-configuration.md#the-global-section) の[グローバルセクションでデバッグロギングを有効にすることができます。config.toml の一番上に以下の行を追加します：

log_level = "debug"

Helmチャートで

GitLab RunnerがGitLab Runner Helm Chartを使用してKubernetesクラスタにインストールされた場合、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.html#the-global-section
##
logLevel: debug

Docker Executor RunnerのDNS設定

GitLab RunnerをDocker executorで設定するとき、ホスト上のRunnerデーモンはGitLabにアクセスできるのに、ビルドされたコンテナはアクセスできないという問題に遭遇することがあります。これは、ホストでDNSが設定されているにもかかわらず、その設定がコンテナに渡されていない場合に起こる可能性があります。

例

GitLabサービスとGitLab Runnerは2つの異なるネットワークに存在し、2つの方法でブリッジされています（例えば、インターネット経由とVPN経由）。RunnerがGitLabサービスを見つけるために使うルーティングメカニズムがDNSをクエリする場合、コンテナのDNS設定はVPN経由のDNSサービスを使うことを知らず、インターネット経由で提供されるものをデフォルトにするかもしれません。この設定では、次のようなメッセージが表示されます：

Created fresh repository.
++ echo 'Created fresh repository.'
++ git -c 'http.userAgent=gitlab-runner 15.11.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のconfig.toml ファイルの[runners.docker] セクションのdns 設定を使うことで、どのDNSサーバーを使うかをDockerに指示することができます。

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

私が見ているのはx509: certificate signed by unknown authority

自己署名証明書をご覧ください。

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

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.

Unable to query docker version: Cannot connect to the docker engine endpoint というエラーが表示される場合、TLSの失敗が関係している可能性があります。docker-machine をインストールすると、動作しない証明書があります。

このイシューを解決するには、証明書を消去してRunnerを再起動します。再起動すると、Runnerは証明書が空であることに気づき、証明書を再作成します。

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

オートスケールされた Runner への AWS インスタンスプロファイルの追加

AWS IAM ロールを作成すると、IAM コンソールで、ロールにはロール ARNとインスタンスプロファイル ARN があります。ロール名ではなく、インスタンスプロファイル名を使用する必要があります。

[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

エラー：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 Proxyの設定が正しく行われていることを確認してください。特に、独自の設定を持つHTTP Proxyを使用している場合、GitLabのリクエストがGitLab Workhorseソケットにプロキシされ、GitLab Unicornソケットにはプロキシされないことを確認してください。

HTTP(S) 経由のGitプロトコルはGitLab Workhorseによって解決されるため、GitLabのメインエントランスポイントとなります。

Linuxパッケージのインストールを使っていて、バンドルされているNGINXサーバーを使いたくない場合は、バンドルされていないウェブサーバーを使うを読んでください。

GitLab RecipesリポジトリにApacheとNGINXのウェブサーバー設定例があります。

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

ユーザーのイシューの例をご覧ください。

zoneinfo.zip: no such file or directory エラー：Timezone またはOffPeakTimezone

[[docker.machine.autoscaling]] 、タイムゾーンを設定することができます。この機能はほとんどのUnixシステムですぐに動作するはずです。しかし、いくつかのUnixシステム、そしておそらくほとんどの非Unixシステム（GitLab Runnerのバイナリを提供しているWindowsを含む）では、使用するとランナーが開始時に以下のようなエラーでクラッシュします：

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

このエラーは Go のtime パッケージが原因です。Goは指定されたタイムゾーンの設定をロードするためにIANAタイムゾーンデータベースを使用します。ほとんどのUnixシステムでは、このデータベースはよく知られたパス(/usr/share/zoneinfo,/usr/share/lib/zoneinfo,/usr/lib/locale/TZ/)のいずれかにすでに存在しています。Goのtime パッケージは、これら3つのパスすべてからタイムゾーン・データベースを探します。そのどれもが見つからなかった場合でも、マシンにGo開発環境が設定されていれば、$GOROOT/lib/time/zoneinfo.zip ファイルにフォールバックします。

これらのパスが1つも存在しない場合（たとえば本番Windowsホスト）、上記のエラーがスローされます。

お使いのシステムにIANAタイムゾーンデータベースのサポートがあるが、デフォルトでは利用できない場合は、インストールしてみてください。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インスタンスを実行すると、予期しない、デバッグしにくい動作が発生する可能性があります。GitLab Runner 12.2では、GitLab Runnerの単一のインスタンスだけが一度に特定のconfig.toml ファイルを使用することができます。

Job failed (system failure): preparing environment:

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

失敗の原因となることが知られているドットファイルの例：

  • .bash_logout
  • .condarc
  • .rvmrc

SELinuxもこのエラーの原因になることがあります。SELinuxの監査ログを見ることで確認できます：

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

Runner abruptly terminates afterCleaning up stage ランナーがステージ内部で突然終了しました。

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

ジョブがremote error: tls: bad certificate (exec.go:71:0s)

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

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

Helmチャート：ERROR .. Unauthorized

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

ジョブの実行中に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ポッドはもはやアクセスできません。

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

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

Elasticsearch にはvm.max_map_count という要件があり、Elasticsearch を実行するインスタンスに設定する必要があります。

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