GitLab Pages 管理のトラブルシューティング

このページには、GitLab Pages を管理する際に遭遇する可能性のあるイシューのリストがあります。

GitLab Pages のログの見方

Pages デーモンのログを見るには、次のコマンドを実行します：

sudo gitlab-ctl tail gitlab-pages

ログファイルは/var/log/gitlab/gitlab-pages/current にもあります。

unsupported protocol scheme \"\""

以下のようなエラーが表示された場合：

{"error":"failed to connect to internal Pages API: Get \"/api/v4/internal/pages/status\": unsupported protocol scheme \"\"","level":"warning","msg":"attempted to connect to the API","time":"2021-06-23T20:03:30Z"}

これは、Pagesサーバー設定でHTTP(S) プロトコルスキームを設定していないことを意味します。修正するには

  1. /etc/gitlab/gitlab.rb を編集します：

    gitlab_pages['gitlab_server'] = "https://<your_gitlab_server_public_host_and_port>"
gitlab_pages['internal_gitlab_server'] = "https://<your_gitlab_server_private_host_and_port>" # optional, gitlab_pages['gitlab_server'] is used as default

  2. GitLab を再設定します：

    sudo gitlab-ctl reconfigure

GitLab Pages プロキシに接続する際、サーバーが IPv6 でリッスンしていない場合に 502 エラーが発生する問題

サーバーがIPv6をリッスンしていない場合でも、NGINXがデフォルトでIPv6を使用してGitLab Pagesサービスに接続する場合があります。このような場合は、gitlab_pages_error.log に以下のようなログが表示されれば特定できます：

2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com"

これを解決するには、GitLab Pageslisten_proxy の設定に明示的なIPとポートを設定し、GitLab Pagesデーモンがリッスンすべき明示的なアドレスを定義します：

gitlab_pages['listen_proxy'] = '127.0.0.1:8090'

断続的な502エラー、または数日後

systemd とtmpfiles.dを使用しているシステムでPagesを実行している場合、Pagesを提供しようとすると断続的に502エラーが発生することがあります：

dial tcp: lookup gitlab.example.com on [::1]:53: dial udp [::1]:53: connect: no route to host"

GitLab Pages は/etc/hosts のようなファイルを含むバインドマウントを /tmp/gitlab-pages-* の内部に作成します。しかし、systemd は/tmp/ ディレクトリを定期的に掃除するので、DNS 設定が失われる可能性があります。

systemd が Pages 関連のコンテンツを掃除しないようにするには：

  1. Pages/tmp ディレクトリを削除しないようにtmpfiles.d に伝えてください：

    echo 'x /tmp/gitlab-pages-*' >> /etc/tmpfiles.d/gitlab-pages-jail.conf

  2. GitLab Pages を再起動します：

    sudo gitlab-ctl restart gitlab-pages

GitLab Pagesにアクセスできません

GitLab Pagesにアクセスできず（502 Bad Gateway エラーやログインループなど）、Pagesのログにこのエラーが表示されている場合：

"error":"retrieval context done: context deadline exceeded","host":"root.docs-cit.otenet.gr","level":"error","msg":"could not fetch domain information from a source"

  1. /etc/gitlab/gitlab.rb に以下を追加してください：

    gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080'

  2. GitLab Pages を再起動します：

    sudo gitlab-ctl restart gitlab-pages

GitLab API内部への接続に失敗しました。

以下のようなエラーが表示された場合：

ERRO[0010] Failed to connect to the internal GitLab API after 0.50s  error="failed to connect to internal Pages API: HTTP status: 401"

GitLab Pagesを別のサーバーで実行している場合は、GitLab 13.3にアップグレードした後、そのセクションで説明されているように、/etc/gitlab/gitlab-secrets.json ファイルをGitLabサーバーから Pagesサーバーにコピーする必要があります。

その他の理由としては、ファイアウォール設定や閉じたポートなど、GitLabサーバーと Pagesサーバー間のネットワーク接続の問題が考えられます。例えば、接続タイムアウトが発生した場合などです：

error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"

PagesがGitLab APIのインスタンスと通信できません。

domain_config_source=auto のデフォルト値を使用し、GitLab Pages の複数のインスタンスを実行している場合、Pages コンテンツの配信中に断続的に 502 エラーのレスポンスが表示されることがあります。また、Pages のログに以下の警告が表示されることがあります：

WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized"

これは、gitlab-secrets.json ファイルが GitLab Rails と GitLab Pages の間で古い場合に起こる可能性があります。すべての GitLab Pages インスタンスで、Running GitLab Pages on a separate server のステップ 8-10 に従ってください。

AWSネットワークロードバランサーとGitLab Pagesを使用すると、断続的に502エラーが発生します。

クライアントIPの保存が有効になっているネットワークロードバランサーを使用すると、接続がタイムアウトし、リクエストがソースサーバーにループバックされます。これは、コアGitLabアプリケーションとGitLab Pagesの両方を実行している複数のサーバーを持つGitLabインスタンスで発生する可能性があります。また、1つのコンテナでコアGitLabアプリケーションとGitLab Pagesの両方を実行している場合にも発生する可能性があります。

AWSは、このイシューを解決するためにIPターゲットタイプを使用することを推奨します。

コアGitLabアプリケーションとGitLab Pagesが同じホストまたはコンテナ上で実行されている場合、クライアントIPの保存をオフにするとこのイシューが解決する可能性があります。

securecookie: failed to generate random iv 、500エラー。Failed to save the session

この問題は、古いオペレーティング・システムが原因である可能性が高いです。Pages デーモンはsecurecookie ライブラリ を使用して、Go](https://pkg.go.dev/crypto/rand#pkg-variables)の[crypto/rand を介してランダムな文字列を取得します。これにはgetrandom システムコールまたは/dev/urandom がホスト OS 上で利用可能である必要があります。公式にサポートされているオペレーティング・システムにアップグレードすることをお勧めします。

要求されたスコープが無効、不正、または不明です。

この問題は GitLab Pages OAuth アプリケーションの権限に起因しています。修正するには

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 左サイドバーで、Applications > GitLab Pages を選択します。
  4. アプリケーションを編集します。
  5. Scopes]で、api スコープが選択されていることを確認します。
  6. 変更を保存します。

別のGitLabサーバーを運用している場合、この設定はメインのGitLabサーバーで行う必要があります。

ワイルドカードDNSエントリーが設定できない場合の回避策

ワイルドカードDNSの前提条件が満たせない場合でも、GitLab Pagesを限定的に使用することができます：

  1. Pagesを使う必要があるすべてのプロジェクトを単一のグループ名前空間に移動します。例えば、pages 。
  2. *.-ワイルドカードを使用しないDNS エントリを設定します（例：pages.example.io）。
  3. gitlab.rb ファイルでpages_external_url http://example.io/ を設定します。グループの名前空間はGitLabによって自動的にプリペンドされるので、ここでは省略します。

Pages デーモンが権限拒否エラーで失敗します。

/tmp がnoexec でマウントされている場合、Pages デーモンは次のようなエラーで起動に失敗します：

{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"}

この場合、TMPDIR をnoexec でマウントされていない場所に変更してください。/etc/gitlab/gitlab.rbに以下を追加します：

gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'}

追加したら、sudo gitlab-ctl reconfigure で再設定し、sudo gitlab-ctl restart でGitLabを再起動します。

The redirect URI included is not valid. Pages アクセスコントロールを使う場合

pages_external_url がある時点で更新された場合、このエラーが表示されることがあります。以下を確認してください：

  1. システムOAuthアプリケーションを確認してください：

    1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
    2. Admin Areaを選択します。
    3. アプリケーション]を選択し、[新しいアプリケーションを追加]を選択します。
    4. コールバック URL/リダイレクト URIが、pages_external_url が使用するように設定されているプロトコル（HTTP または HTTPS）を使用していることを確認します。

  2. Redirect URI のドメインとパスのコンポーネントは有効です:projects.<pages_external_url>/auth のようになるはずです。

500エラーcannot serve from disk

Pagesから500レスポンスがあり、以下のようなエラーが発生した場合：

ERRO[0145] cannot serve from disk                        error="gitlab: disk access is disabled via enable-disk=false" project_id=27 source_path="file:///shared/pages/@hashed/67/06/670671cd97404156226e507973f2ab8330d3022ca96e0c93bdbdb320c41adcaf/pages_deployments/14/artifacts.zip" source_type=zip

これは、GitLab RailsがGitLab Pagesにディスク上の場所からコンテンツを提供するように指示しているが、GitLab Pagesがディスクアクセスを無効にするように設定されていることを意味します。

ディスクアクセスを有効にするには

  1. /etc/gitlab/gitlab.rb で GitLab Pages のディスクアクセスを有効にします：

    gitlab_pages['enable_disk'] = true

  2. GitLab を再設定します。

httprange: new resource 403

以下のようなエラーが表示されたら、GitLabを再設定してください：

{"error":"httprange: new resource 403: \"403 Forbidden\"","host":"root.pages.example.com","level":"error","msg":"vfs.Root","path":"/pages1/","time":"2021-06-10T08:45:19Z"}

NFS経由でファイルを同期している別のサーバーでpagesを実行している場合、共有pagesディレクトリがメインのGitLabサーバーとGitLab Pagesサーバーで異なるパスにマウントされている可能性があります。

その場合、オブジェクトストレージを設定し、既存のページデータをマイグレーションすることを強くお勧めします。

あるいは、GitLab Pages共有ディレクトリを両方のサーバーの同じパスにマウントすることもできます。

GitLab 14.0以上にアップグレード後、GitLab Pagesが動作しません。

GitLab 14.0では、GitLab Pagesに多くの変更が加えられており、手動での操作が必要になる場合があります。

  1. まずはマイグレーションガイドに従ってください。
  2. GitLab 14.3以上にアップグレードしてみてください。いくつかのイシューはGitLab 14.1、14.2、14.3で修正されました。
  3. もしうまくいかない場合は、GitLab Pagesのログを見て、もしそこにエラーがあれば、このページで検索してみてください。
caution
GitLab 14.0-14.2では、レガシーストレージや設定メカニズムを一時的に有効にすることができます。

そのためには

  1. マイグレーションフィードバックのイシューに表示されている問題を記述してください。

  2. /etc/gitlab/gitlab.rb を編集します：

    gitlab_pages['use_legacy_storage'] = true

  3. GitLab を再設定します。

GitLab Pagesのデプロイジョブが “is not a recognized provider “というエラーで失敗します。

Pagesジョブは成功したが、デプロイジョブが“is not a recognized provider” というエラーを出した場合：

Pages Deploy Failure

エラーメッセージis not a recognized provider は、GitLabがオブジェクトストレージのためにクラウドプロバイダに接続するために使用するfog gemから来ている可能性があります。

これを修正するには

  1. gitlab.rb ファイルを確認してください。gitlab_rails['pages_object_store_enabled'] が有効になっているにもかかわらず、バケツの詳細が設定されていない場合：

    • S3互換接続設定ガイドに従って、Pagesデプロイ用にオブジェクトストレージを設定します。
    • この行をコメントアウトして、デプロイをローカルに保存します。

  2. gitlab.rb ファイルに加えた変更を保存し、GitLab を再設定してください。

404エラーThe page you're looking for could not be found

GitLab Pagesから404 Page Not Found ：

  1. .gitlab-ci.yml にジョブpages: が含まれているか確認してください。
  2. 現在のプロジェクトのパイプラインをチェックし、ジョブpages:deploy が実行されていることを確認します。

pages:deploy のジョブがないと、GitLab Pages サイトの更新は公開されません。