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

次のセクションでは、Gitalyエラーに対する考えられる解決策を示します。

Gitalyタイムアウト設定、およびgitaly/currentファイルの解析に関するアドバイスも参照してください。

スタンドアロンGitalyサーバーを使用する場合は、バージョンを確認してください

スタンドアロンGitalyサーバーを使用する場合は、完全な互換性を確保するために、GitLabと同じバージョンであることを確認する必要があります:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 概要 > Gitalyサーバーを選択します。
3. すべてのGitalyサーバーが最新であることを示していることを確認します。

リポジトリストレージリソースの詳細を検索します

Gitalyストレージで使用可能なスペースと使用済みのスペースを判断するには、Railsコンソールで次のコマンドを実行します:

Gitlab::GitalyClient::ServerService.new("default").storage_disk_statistics
# For Gitaly Cluster (Praefect)
Gitlab::GitalyClient::ServerService.new("<storage name>").disk_statistics

gitaly-debugを使用する

gitaly-debugコマンドは、GitalyおよびGitのパフォーマンスに関する「本番環境デバッグ」ツールを提供します。これは、本番環境のエンジニアとサポートエンジニアがGitalyのパフォーマンスの問題を調査するのに役立つことを目的としています。

サポートされているサブコマンドの一覧については、gitaly-debugのヘルプページを参照してください:

gitaly-debug -h

トラブルシューティングにGitが必要な場合はgitaly gitを使用してください

gitaly gitを使用して、デバッグまたはテストの目的で、Gitalyと同じGit実行環境を使用してGitコマンドを実行します。gitaly gitは、バージョンの互換性を確保するための推奨される方法です。

gitaly gitは、すべての引数を基になるGit呼び出しに渡し、Gitがサポートするすべての形式の入力をサポートします。gitaly gitを使用するには、次を実行します:

sudo -u git -- /opt/gitlab/embedded/bin/gitaly git <git-command>

たとえば、リポジトリの作業ディレクトリ内のLinuxパッケージのインスタンスで、Gitalyを介してgit ls-treeを実行するには、次のようにします:

sudo -u git -- /opt/gitlab/embedded/bin/gitaly git ls-tree --name-status HEAD

コミット、プッシュ、およびクローンは401を返します

remote: GitLab: 401 Unauthorized

gitlab-secrets.jsonファイルをGitLabアプリケーションノードと同期する必要があります。

500エラーとfetching folder contentエラーがリポジトリページに表示される

Fetching folder contentエラー（場合によっては500エラー）は、GitLabとGitaly間の接続の問題を示しています。詳細については、クライアント側のgRPCログ記録を参照してください。

クライアント側のgRPCログ記録

Gitalyは、gRPC RPCフレームワークを使用します。Ruby gRPCクライアントには独自のログファイルがあり、Gitalyエラーが発生した場合に役立つ情報が含まれている場合があります。GRPC_LOG_LEVEL環境変数を使用して、gRPCクライアントのログレベルを制御できます。デフォルトレベルはWARNです。

次のコマンドでgRPCトレースを実行できます:

sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check

このコマンドがfailed to connect to all addressesエラーで失敗する場合は、SSLまたはTLSの問題を確認してください:

/opt/gitlab/embedded/bin/openssl s_client -connect <gitaly-ipaddress>:<port> -verify_return_error

Verify return codeフィールドが既知のLinuxパッケージインストール設定の問題を示しているかどうかを確認します。

opensslは成功したが、gitlab-rake gitlab:gitaly:checkは失敗した場合は、Gitalyの証明書の要件を確認してください。

サーバー側のgRPCログ記録

gRPCトレーシングは、GODEBUG=http2debug環境変数を使用して、Gitaly自体で有効にすることもできます。Linuxパッケージインストールでこれを設定するには、次のようにします:

1. 次の内容をgitlab.rbファイルに追加します:

   gitaly['env'] = {
     "GODEBUG=http2debug" => "2"
   }

2. GitLabを再構成します。

GitプロセスとRPCの関連付け

特定のGitプロセスを作成したGitaly RPCを特定する必要がある場合があります。

これを行う1つの方法は、DEBUGロギングを使用することです。ただし、これを事前に有効にする必要があり、生成されるログは詳細です。

この関連付けを行うための軽量な方法は、Gitプロセスの実行環境（そのPIDを使用）を調べて、CORRELATION_ID変数を確認することです:

PID=<Git process ID>
sudo cat /proc/$PID/environ | tr '\0' '\n' | grep ^CORRELATION_ID=

この方法はgit cat-fileプロセスでは信頼性がありません。これは、Gitalyが内部的にそれらをRPC間でプールし、再利用するためです。

リポジトリの変更が401 Unauthorizedエラーで失敗する

Gitalyを独自のサーバーで実行し、次の条件に気付いた場合:

• ユーザーは、SSHとHTTPSの両方を使用して、リポジトリを正常に複製およびフェッチできます。
• ユーザーはリポジトリにプッシュできないか、Web UIで変更を加えようとすると、401 Unauthorizedメッセージが表示されます。

Gitalyクライアントに認証できないのは、間違ったシークレットファイルがあるためです。

以下がすべて当てはまることを確認してください:

• ユーザーがこのGitalyサーバー上のリポジトリに対してgit pushプッシュを実行すると、401 Unauthorizedエラーで失敗します:

  remote: GitLab: 401 Unauthorized
  To <REMOTE_URL>
  ! [remote rejected] branch-name -> branch-name (pre-receive hook declined)
  error: failed to push some refs to '<REMOTE_URL>'

• ユーザーがGitLab UIを使用してリポジトリからファイルを追加または変更すると、すぐに赤い401 Unauthorizedバナーが表示されて失敗します。

• 新しいプロジェクトを作成し、Readmeで初期化すると、プロジェクトは正常に作成されますが、Readmeは作成されません。

• Gitalyクライアントでログをテールするときにエラーを再現すると、/api/v4/internal/allowedエンドポイントに到達すると401エラーが発生します。

  # api_json.log
  {
    "time": "2019-07-18T00:30:14.967Z",
    "severity": "INFO",
    "duration": 0.57,
    "db": 0,
    "view": 0.57,
    "status": 401,
    "method": "POST",
    "path": "\/api\/v4\/internal\/allowed",
    "params": [
      {
        "key": "action",
        "value": "git-receive-pack"
      },
      {
        "key": "changes",
        "value": "REDACTED"
      },
      {
        "key": "gl_repository",
        "value": "REDACTED"
      },
      {
        "key": "project",
        "value": "\/path\/to\/project.git"
      },
      {
        "key": "protocol",
        "value": "web"
      },
      {
        "key": "env",
        "value": "{\"GIT_ALTERNATE_OBJECT_DIRECTORIES\":[],\"GIT_ALTERNATE_OBJECT_DIRECTORIES_RELATIVE\":[],\"GIT_OBJECT_DIRECTORY\":null,\"GIT_OBJECT_DIRECTORY_RELATIVE\":null}"
      },
      {
        "key": "user_id",
        "value": "2"
      },
      {
        "key": "secret_token",
        "value": "[FILTERED]"
      }
    ],
    "host": "gitlab.example.com",
    "ip": "REDACTED",
    "ua": "Ruby",
    "route": "\/api\/:version\/internal\/allowed",
    "queue_duration": 4.24,
    "gitaly_calls": 0,
    "gitaly_duration": 0,
    "correlation_id": "XPUZqTukaP3"
  }
  
  # nginx_access.log
  [IP] - - [18/Jul/2019:00:30:14 +0000] "POST /api/v4/internal/allowed HTTP/1.1" 401 30 "" "Ruby"

この問題を解決するには、Gitalyサーバー上のgitlab-secrets.jsonファイルが、Gitalyクライアント上のファイルと一致することを確認します。一致しない場合は、Gitalyサーバー上のシークレットファイルをGitalyクライアントと一致するように更新してから、設定を再構成します。

gitlab-secrets.jsonファイルがすべてのGitalyサーバーとクライアントで同じであることを確認した場合、アプリケーションはこのシークレットを別のファイルからフェッチしている可能性があります。Gitalyサーバーのconfig.toml fileは、使用中のシークレットファイルを示しています。

リポジトリのプッシュが401 UnauthorizedとJWT::VerificationErrorで失敗する

git pushを試みるときに、次のことがわかります:

• 401 Unauthorizedエラー。

• サーバーログの次の内容:

  {
    ...
    "exception.class":"JWT::VerificationError",
    "exception.message":"Signature verification raised",
    ...
  }

このエラーの組み合わせは、GitLabサーバーがGitLab 15.5以降にアップグレードされたが、Gitalyがまだアップグレードされていない場合に発生します。

GitLab 15.5以降では、共有シークレットの代わりにJWTトークンを使用してGitLab Shellで認証します。GitLabサーバーをアップグレードする前に、外部Gitalyサーバーをアップグレードする必要があります。

リポジトリのプッシュがdeny updating a hidden refエラーで失敗する

Gitalyには、ユーザーが更新することを許可されていない、読み取り専用の内部GitLab参照があります。git push --mirrorで内部参照を更新しようとすると、Gitは拒否エラーdeny updating a hidden refを返します。

次の参照は読み取り専用です:

• refs/environments/
• refs/keep-around/
• refs/merge-requests/
• refs/pipelines/

ブランチとタグ付けのみをミラープッシュし、保護されたrefsのミラープッシュを試行しないようにするには、次を実行します:

git push --force-with-lease origin 'refs/heads/*:refs/heads/*' 'refs/tags/*:refs/tags/*'

管理者がプッシュするその他のネームスペースは、追加のref仕様を介してそこにも含めることができます。

コマンドラインツールがGitalyに接続できない

次の場合、gRPCはGitalyサーバーに到達できません:

• コマンドラインツールを使用してGitalyサーバーに接続できません。
• 特定のアクションを実行すると、14: Connect Failedエラーメッセージが表示されます。

TCPを使用してGitalyに到達できることを確認します:

sudo gitlab-rake gitlab:tcp_check[GITALY_SERVER_IP,GITALY_LISTEN_PORT]

TCP接続の場合:

• 失敗した場合は、ネットワーク設定とファイアウォールルールを確認してください。
• 成功した場合は、ネットワーキングとファイアウォールルールは正しいです。

Bashなどのコマンドライン環境でプロキシサーバーを使用している場合、これらがgRPCトラフィックに干渉する可能性があります。

Bashまたは互換性のあるコマンドライン環境を使用している場合は、次のコマンドを実行して、プロキシサーバーが設定されているかどうかを判断します:

echo $http_proxy
echo $https_proxy

これらの変数のいずれかに値がある場合、Gitaly CLI接続は、Gitalyに接続できないプロキシを介してルーティングされている可能性があります。

プロキシ設定を削除するには、次のコマンドを実行します（どの変数に値があるかによって異なります）:

unset http_proxy
unset https_proxy

リポジトリへのアクセス時にGitalyログまたはPraefectログに表示されるアクセス許可拒否エラー

GitalyログおよびPraefectログに次の内容が表示される場合があります:

{
  ...
  "error":"rpc error: code = PermissionDenied desc = permission denied: token has expired",
  "grpc.code":"PermissionDenied",
  "grpc.meta.client_name":"gitlab-web",
  "grpc.request.fullMethod":"/gitaly.ServerService/ServerInfo",
  "level":"warning",
  "msg":"finished unary call with code PermissionDenied",
  ...
}

ログ内のこの情報は、gRPC呼び出しのエラー応答コードです。

このエラーが発生した場合（Gitaly認証トークンが正しくセットアップされている場合でも）、Gitalyサーバーでクロックドリフトが発生している可能性があります。Gitalyに送信される認証トークンにはタイムスタンプが含まれています。有効と見なされるには、Gitalyは、そのタイムスタンプがGitalyサーバー時間の60秒以内であることを要求します。

Gitalyクライアントとサーバーが同期されていることを確認し、ネットワークタイムプロトコル（NTP）タイムサーバーを使用してそれらを同期された状態に保ちます。

設定を再構成した後、Gitalyが新しいアドレスをリッスンしない

gitaly['configuration'][:listen_addr]またはgitaly['configuration'][:prometheus_listen_addr]の値を更新すると、sudo gitlab-ctl reconfigureの後でも、Gitalyは古いアドレスでリッスンし続ける場合があります。

これが発生した場合は、sudo gitlab-ctl restartを実行して問題を解決します。この問題は解決されているため、これは不要になっているはずです。

ヘルスチェックの警告

/var/log/gitlab/praefect/currentの次の警告は無視できます。

"error":"full method name not found: /grpc.health.v1.Health/Check",
"msg":"error when looking up method info"

ファイルが見つからないエラー

/var/log/gitlab/gitaly/currentの次のエラーは無視できます。これらは、GitLab Railsアプリケーションが、リポジトリに存在しない特定のファイルを確認することによって発生します。

"error":"not found: .gitlab/route-map.yml"
"error":"not found: Dockerfile"
"error":"not found: .gitlab-ci.yml"

Dynatraceが有効になっていると、Gitのプッシュが遅くなる

Dynatraceは、sudo -u git -- /opt/gitlab/embedded/bin/gitaly-hooks参照トランザクションフックを起動およびシャットダウンするのに数秒かかるようにする可能性があります。gitaly-hooksは、ユーザーがプッシュするときに2回実行されるため、大幅な遅延が発生します。

Dynatraceが有効になっているときにGitのプッシュが遅すぎる場合は、Dynatraceを無効にします。

gitaly checkが401ステータスコードで失敗する

Gitalyが内部GitLab APIにアクセスできない場合、gitaly checkが401ステータスコードで失敗する可能性があります。

これを解決する1つの方法は、gitlab_rails['internal_api_url']でgitlab.rbに設定されているGitLab内部API API URLのエントリが正しいことを確認することです。

Gitaly TLSを使用している場合、新しいマージリクエストの変更（差分）が読み込まれない

TLSを使用したGitalyを有効にした後、新しいマージリクエストの変更（差分）が生成されず、GitLabに次のメッセージが表示されます:

Building your merge request... This page will update when the build is complete

Gitalyは、一部の操作を完了するために、それ自体に接続できる必要があります。GitalyサーバーがGitaly証明書を信頼していない場合、マージリクエストの差分は生成できません。

Gitalyがそれ自体に接続できない場合は、次のメッセージのようなGitalyログにメッセージが表示されます:

{
   "level":"warning",
   "msg":"[core] [Channel #16 SubChannel #17] grpc: addrConn.createTransport failed to connect to {Addr: \"ext-gitaly.example.com:9999\", ServerName: \"ext-gitaly.example.com:9999\", }. Err: connection error: desc = \"transport: authentication handshake failed: tls: failed to verify certificate: x509: certificate signed by unknown authority\"",
   "pid":820,
   "system":"system",
   "time":"2023-11-06T05:40:04.169Z"
}
{
   "level":"info",
   "msg":"[core] [Server #3] grpc: Server.Serve failed to create ServerTransport: connection error: desc = \"ServerHandshake(\\\"x.x.x.x:x\\\") failed: wrapped server handshake: remote error: tls: bad certificate\"",
   "pid":820,
   "system":"system",
   "time":"2023-11-06T05:40:04.169Z"
}

問題を解決するには、Gitaly証明書をGitalyサーバーの/etc/gitlab/trusted-certsフォルダーに追加したことを確認してください:

1. 証明書がシンボリックリンクされるようにGitLabを再構成する
2. Gitalyプロセスによって証明書が読み込まれるように、手動でsudo gitlab-ctl restart gitalyを再起動します。

Gitalyがnoexecファイルシステムに保存されているプロセスをフォークできない

noexecオプションをマウントポイント（たとえば、/var）に適用すると、Gitalyがプロセスのフォークに関連するpermission deniedエラーをスローします。例:

fork/exec /var/opt/gitlab/gitaly/run/gitaly-2057/gitaly-git2go: permission denied

この問題を解決するには、ファイルシステムマウントからnoexecオプションを削除します。別の方法として、Gitalyのランタイムディレクトリを変更することもできます:

1. /etc/gitlab/gitlab.rbにgitaly['runtime_dir'] = '<PATH_WITH_EXEC_PERM>'を追加し、noexecが設定されていない場所を指定します。
2. sudo gitlab-ctl reconfigureを実行します。

コミットの署名がinvalid argumentまたはinvalid dataで失敗する

コミットの署名が次のいずれかのエラーで失敗した場合:

• invalid argument: signing key is encrypted
• invalid data: tag byte does not have MSB set

このエラーが発生するのは、Gitalyのコミット署名がヘッドレスであり、特定のユーザーに関連付けられていないためです。GPG署名キーは、パスフレーズなしで作成するか、エクスポートする前にパスフレーズを削除する必要があります。

Gitalyログにinfoメッセージのエラーが表示される

GitLab 16.3で導入されたバグにより、追加のエントリがGitalyログに書き込まれました。これらのログエントリには"level":"info"が含まれていましたが、msg文字列にエラーが含まれているように見えました。

例:

{"level":"info","msg":"[core] [Server #3] grpc: Server.Serve failed to create ServerTransport: connection error: desc = \"ServerHandshake(\\\"x.x.x.x:x\\\") failed: wrapped server handshake: EOF\"","pid":6145,"system":"system","time":"2023-12-14T21:20:39.999Z"}

このログエントリの理由は、基盤となるgRPCライブラリが詳細な転送ログを出力することがあるためです。これらのログエントリはエラーのように見えますが、一般的には無視してもかまいません。

このバグは、GitLab 16.4.5、16.5.5、および16.6.0で修正され、これらの種類のメッセージがGitalyログに書き込まれないようになっています。

Gitalyのプロファイリング

Gitalyは、Prometheusリスンポートで、いくつかのGo組み込みパフォーマンスプロファイリングツールを公開します。たとえば、PrometheusがGitLabサーバーのポート9236をリッスンしている場合:

• 実行中のgoroutinesのリストとそのバックトレースを取得します:

  curl --output goroutines.txt "http://<gitaly_server>:9236/debug/pprof/goroutine?debug=2"

• 30秒間、CPUプロファイルを呼び出すします:

  curl --output cpu.bin "http://<gitaly_server>:9236/debug/pprof/profile"

• ヒープメモリ使用量をプロファイルします:

  curl --output heap.bin "http://<gitaly_server>:9236/debug/pprof/heap"

• 5秒間の実行トレースを記録します。これは、実行中のGitalyのパフォーマンスに影響を与えます:

  curl --output trace.bin "http://<gitaly_server>:9236/debug/pprof/trace?seconds=5"

goがインストールされているホストでは、CPUプロファイルとヒーププロファイルをブラウザで表示できます:

go tool pprof -http=:8001 cpu.bin
go tool pprof -http=:8001 heap.bin

実行トレースは、次を実行して表示できます:

go tool trace heap.bin

Git操作のプロファイル

Git操作に関する追加情報をGitalyログに送信することで、Gitalyが実行するGit操作をプロファイルできます。この情報により、ユーザーはパフォーマンス最適化、デバッグ、および一般的なテレメトリ収集に関するインサイトをより深く得ることができます。詳細については、Git Trace2 APIリファレンスを参照してください。

システムオーバーロードを防ぐため、追加の情報ロギングはレート制限されています。レート制限を超過すると、トレースはスキップされます。ただし、レートが正常な状態に戻ると、トレースは自動的に再度処理されます。レート制限により、システムの安定性が維持され、過剰なトレース処理による悪影響が回避されます。

GitLabの復元後、リポジトリが空として表示される

セキュリティを強化するためにfapolicydを使用すると、GitLabのバックアップファイルからの復元が成功したとGitLabからレポートされる場合がありますが、次のような状態になることがあります:

• リポジトリが空として表示される。

• 新しいファイルを作成すると、次のようなエラーが発生する:

  13:commit: commit: starting process [/var/opt/gitlab/gitaly/run/gitaly-5428/gitaly-git2go -log-format json -log-level -correlation-id
  01GP1383JV6JD6MQJBH2E1RT03 -enabled-feature-flags -disabled-feature-flags commit]: fork/exec /var/opt/gitlab/gitaly/run/gitaly-5428/gitaly-git2go: operation not permitted.

• Gitalyログに次のようなエラーが含まれている可能性がある:

   "error": "exit status 128, stderr: \"fatal: cannot exec '/var/opt/gitlab/gitaly/run/gitaly-5428/hooks-1277154941.d/reference-transaction':
  
    Operation not permitted\\nfatal: cannot exec '/var/opt/gitlab/gitaly/run/gitaly-5428/hooks-1277154941.d/reference-transaction': Operation
    not permitted\\nfatal: ref updates aborted by hook\\n\"",
   "grpc.code": "Internal",
   "grpc.meta.deadline_type": "none",
   "grpc.meta.method_type": "client_stream",
   "grpc.method": "FetchBundle",
   "grpc.request.fullMethod": "/gitaly.RepositoryService/FetchBundle",
  ...

デバッグモードを使用すると、fapolicydが現在のルールに基づいて実行を拒否しているかどうかを判断できます。

fapolicydが実行を拒否していることが判明した場合は、以下を検討してください:

1. /var/opt/gitlab/gitaly設定で、fapolicyd内のすべての実行可能ファイルを許可します:

   allow perm=any all : ftype=application/x-executable dir=/var/opt/gitlab/gitaly/

2. サービスを再起動します:

   sudo systemctl restart fapolicyd
   
   sudo gitlab-ctl restart gitaly

Pre-receive hook declinedが有効なRHELインスタンスへのプッシュ時に発生するfapolicyd

fapolicydが有効なRHELベースのインスタンスにプッシュすると、Pre-receive hook declinedエラーが発生する場合があります。このエラーは、fapolicydがGitalyバイナリの実行をブロックできるために発生する可能性があります。この問題を解決するには、次のいずれかの方法を実行します:

• fapolicydを無効にします。
• fapolicydルールを作成して、fapolicydが有効な場合にGitalyバイナリの実行を許可します。

Gitalyバイナリの実行を許可するルールを作成するには:

1. /etc/fapolicyd/rules.d/89-gitlab.rulesファイルを作成します。

2. 次に示すコードをファイルに入力します:

   allow perm=any all : ftype=application/x-executable dir=/var/opt/gitlab/gitaly/

3. サービスを再起動します:

   systemctl restart fapolicyd

新しいルールは、デーモンの復元後に有効になります。

重複パスを持つストレージを削除した後に、リポジトリを更新する

GitLab 17.0では、重複パスを持つストレージの設定のサポートが削除されました。これは、gitaly設定から重複するストレージの設定を削除する必要があることを意味する場合があります。

別のストレージと同じパスを使用したストレージをGitaly設定から削除する場合、古いストレージに関連付けられているプロジェクトを新しいストレージに再割り当てする必要があります。

たとえば、次のような設定になっている場合があります:

gitaly['configuration'] = {
  storage: [
    {
       name: 'default',
       path: '/var/opt/gitlab/git-data/repositories',
    },
    {
       name: 'duplicate-path',
       path: '/var/opt/gitlab/git-data/repositories',
    },
  ],
}

duplicate-pathを設定から削除する場合、割り当てられているプロジェクトを代わりにdefaultに関連付けるには、次のRakeタスクを実行します:

sudo gitlab-rake "gitlab:gitaly:update_removed_storage_projects[duplicate-path, default]"

sudo -u git -H bundle exec rake "gitlab:gitaly:update_removed_storage_projects[duplicate-path, default]" RAILS_ENV=production

エラー: fatal: deflate error (0)\n (ZIPファイルとしてリポジトリをダウンロードする場合)

Gitバージョン2.51で修正されたGitバグ (issue 575) が原因で、場合によっては、リポジトリをZIPアーカイブとしてダウンロードすると、不完全なZIPファイルになることがあります。この場合、Gitalyログに次のエラーが表示されます:

  "msg": "fatal: deflate error (0)\n",

この問題を解決するには、修正されたバージョンのGitを使用するバージョンのGitLabおよびGitalyにアップグレードします。アップグレードできない場合は、次の手順に従って問題を回避してください: