GitLab

冒頭まとめ GitLab の API や Git 操作で 503 Service Unavailable が返ったら、まず応答の本文と Retry-After ヘッダーを確認してください。503 だけでは、原因を一つに決められません。 Gitaly の資源不足を示す本文なら、同時に実行されている処理や待ち行列が手がかりになります。一方、応答の大きさが上限を超えたことを示す本文なら、待つだけでは解消しない問題です。保守モード中の書き込みも 503 になる場合があります。 エラーの概要 API から返る応答の一例です。Gitaly は、GitLab で Git リポジトリへのアクセスを扱う部品です。 HTTP/1.1 503 Service Unavailable {"message":"Upstream Gitaly has been exhausted. Try again later"} この本文は、GitLab のGitaly エラー処理の実装にある文言の一つです。503 の本文は原因や応答を返した部品によって異なり、JSON とは限りません。Git コマンドやブラウザーでも、同じ本文がそのまま表示されるとは限りません。 まず最初に：応答と障害情報を確認する API で失敗した場合は、状態コードと本文に加えて、Retry-After があるか確認します。以下は読み取り要求の例です。URL とプロジェクト ID は実際の接続先に置き換えてください。 curl -i --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ "https://gitlab.example.com/api/v4/projects/1/repository/commits" GITLAB_TOKEN は事前に設定したアクセストークンです。応答やコマンドの記録を共有する際は、トークンなどの秘密情報を含めないでください。 Retry-After があれば、指定された待ち時間を守って再試行します。書き込み要求で失敗した場合は、重複した変更を避けるため、再実行する前に対象の状態も確認してください。 GitLab.com を利用している場合は、GitLab の稼働状況ページでも障害や保守の情報を確認できます。自分で運用する GitLab の場合は、その環境の管理者に確認してください。 よくある原因と解決手順 Gitaly の資源不足 Upstream Gitaly has been exhausted と表示された場合は、Gitaly に関わる処理が資源不足として扱われています。GitLab の実装では、詳細な制限エラーや RESOURCE_EXHAUSTED を、この文言を含むエラーへ変換する経路があります。本文だけで同時実行数が原因だと断定せず、管理者は Gitaly のログや監視情報も確認してください。 ...

冒頭まとめ GitLab の 502 には、他のソフトウェアにはない手がかりがあります。専用の画面が用意されていて、応答に時間がかかりすぎている、という趣旨の文言が表示されます。この文言が出ているかどうかが、切り分けの起点になります。 専用の画面が表示されているなら、応答を作ったのは GitLab に同梱されている前段のソフトウェアです。つまり、前段は動いています。動いていない相手は、その後ろにいる応用処理の側です。逆に、素っ気ない画面や別の形式の画面が出ているなら、応答を作ったのは GitLab の外側にいる中継役です。この場合、GitLab の設定をいくら見直しても変わりません。 GitLab の構成は多段です。前段が受け取り、補助の役が中継し、応用処理が実際の処理を行い、その先に格納の役が控えています。502 が起きるのは、このどこかで応答が返らなくなったときです。段が多いぶん、どこで止まったかを特定する作業が要ります。 公式の窓口記事には、具体的な設定に起因する例が挙げられています。応用処理を単独で動かす設定にしていると、頻繁な再起動が起き、その際に 502 が表示される、というものです。この設定は資源の限られた環境向けのもので、外すと複数の処理単位で動くようになり、順に入れ替える方式が使えるため、停止する時間が短くなる、と説明されています。 エラーの概要 利用者側に表示されるのは、GitLab が用意した専用の画面です。時間がかかりすぎている、という趣旨の文言が入ります。 前段の記録には、その先へ繋げなかったことが残ります。 upstream prematurely closed connection while reading response header from upstream connect() failed (111: Connection refused) while connecting to upstream, upstream: "http://unix:/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket:/" 転送先として、ファイルを経由した接続先が記録されているのが特徴です。この経路で繋がらないということは、応用処理が待ち受けていないか、応答を返す前に落ちているということです。 各段の稼働状況は、まとめて確認できます。 run: gitaly: (pid 1580) 83s; run: log: (pid 1575) 83s run: nginx: (pid 1588) 83s; run: log: (pid 1584) 83s run: puma: (pid 12394) 0s; run: log: (pid 1574) 83s run: sidekiq: (pid 12015) 2s; run: log: (pid 1578) 83s ここで見るべきは、右側の経過時間です。他の段が同じくらいの値なのに、応用処理の段だけが数秒しか経っていない場合、その段が繰り返し起動し直していることを示します。この形は、後述する再起動の問題に直結します。 ...

エラーの概要 GitLabの429エラー（Too Many Requests）は、GitLab APIのレート制限に達したことを示します。ユーザーまたはCI/CDパイプラインが短時間に許可された上限を超えるAPIリクエストを送信した場合に発生します。デフォルトのレート制限はエンドポイントやインスタンスの構成によって異なり、一般的には認証ユーザーは1分間に600リクエスト、未認証の場合は300リクエスト程度とされていますが、パッケージレジストリAPIなど特定のエンドポイントではより高い制限が適用される場合もあります。 実際のエラーメッセージ例 GitLab APIレスポンス： { "message": "429 Too Many Requests", "retry_after": 60, "ratelimit_limit": 600, "ratelimit_remaining": 0, "ratelimit_reset": 1699564800 } curlコマンドでのレスポンス： $ curl -H "PRIVATE-TOKEN: <your-access-token>" https://gitlab.example.com/api/v4/projects HTTP/1.1 429 Too Many Requests RateLimit-Limit: 600 RateLimit-Remaining: 0 RateLimit-Reset: 1699564800 Retry-After: 60 {"message":"429 Too Many Requests"} よくある原因と解決手順 原因1：短時間に多数のAPIリクエストを送出する処理 スクリプトやツールが迅速に連続したAPIコールを実行する際、GitLabのレート制限に即座に到達します。例えば、多数のプロジェクトやグループのメタデータを一括取得する場合、ループ処理で制限を超えやすくなります。 解決策：ページング機能を使用して効率的に取得する import requests import time TOKEN = "<your-access-token>" GITLAB_URL = "https://gitlab.example.com" headers = {"PRIVATE-TOKEN": TOKEN} # ページング機能を使用して効率的に取得 page = 1 while True: response = requests.get( f"{GITLAB_URL}/api/v4/projects", headers=headers, params={"page": page, "per_page": 100} ) if response.status_code == 429: reset_time = int(response.headers.get("RateLimit-Reset", 0)) current_time = int(time.time()) wait_seconds = reset_time - current_time print(f"Rate limit hit. Waiting {wait_seconds} seconds...") time.sleep(max(wait_seconds + 1, 0)) continue if response.status_code != 200: break for project in response.json(): print(f"Project: {project['name']}") if "next" not in response.links: break page += 1 原因2：CI/CDパイプラインが短時間に大量のAPIコールを実行している GitLabのCI/CDパイプラインで複数のジョブが並行実行される場合、各ジョブが独立してAPIを呼び出すと累積的にレート制限に達します。特に、依存関係の解決やアーティファクトダウンロードで多数のAPI呼び出しが発生する環境では顕著です。 ...

エラーの概要 GitLabの500エラーは、GitLabサーバー側で予期しない内部エラーが発生したことを示します。クライアント側の問題ではなく、GitLabのインフラストラクチャまたはアプリケーションレイヤーで何らかの処理に失敗した状態です。このエラーが発生すると、リポジトリーへのアクセス、プッシュ、マージリクエストの操作など、あらゆるGitLab機能が一時的に利用できなくなります。 実際のエラーメッセージ例 ブラウザでGitLabにアクセスした際の表示： 500 Internal Server Error An internal server error occurred. GitLab APIを呼び出した際のレスポンス： { "message": "500 Internal Server Error", "status": 500 } ターミナルからgit操作を実行した際のエラー： $ git push origin main fatal: unable to access 'https://gitlab.example.com/project.git/': The requested URL returned error: 500 よくある原因と解決手順 原因1：GitLabインフラの一時的な障害 GitLabのサーバーインフラストラクチャ側で一時的な障害が発生している場合、リクエストを処理できず500エラーが返却されます。これはデータベース接続の喪失、メモリ不足、ディスク容量の枯渇、または主要サービス（Sidekiq、Puma等）のクラッシュなど、複数の要因が考えられます。 解決手順： # まずstatus.gitlab.comで障害状況を確認する curl -s https://status.gitlab.com/api/v2/status.json | jq '.status' # WebUIで直接確認することもできる # https://status.gitlab.com にアクセスして「All Systems Operational」を確認 # 数分待機してから再試行する sleep 300 git push origin main GitLabの障害情報は status.gitlab.com で公開されています。ここで「All Systems Operational」と表示されていれば、インフラレベルの障害ではなく、個別リポジトリーやアカウント固有の問題である可能性が高くなります。 原因2：リポジトリのGitオブジェクト破損 GitLab内のリポジトリーが保存されているディスク上のGitオブジェクトが破損した場合、リポジトリーの読み書き処理で500エラーが発生します。これはハードウェア障害、不正なシャットダウン、ファイルシステムエラーなどに起因することがあります。 解決手順： ...

エラーの概要 GitLabの404エラーは、指定したプロジェクト・マージリクエスト・ファイルなどのリソースが見つからないことを意味します。API呼び出しやWebUIでのアクセス時に発生し、プロジェクトの存在確認、アクセス権限、リソースパスの誤入力などが主な原因です。プロジェクトが削除された、URLエンコーディングが正しくない、トークンの権限が不足している場合にも表示されます。 実際のエラーメッセージ例 GitLab API経由でのレスポンス： { "message": "404 Not Found" } curlコマンドでの出力： $ curl -H "PRIVATE-TOKEN: <your-token>" "https://gitlab.com/api/v4/projects/wrong-namespace%2Fproject-name" {"message":"404 Not Found"} WebUIでのブラウザ表示： 404 Not Found The page you're looking for could not be found. Python requests ライブラリでのエラー： import requests response = requests.get( "https://gitlab.com/api/v4/projects/invalid-path", headers={"PRIVATE-TOKEN": "<your-token>"} ) print(response.status_code) # 404 よくある原因と解決手順 原因1：プロジェクトIDまたはパスの誤入力 GitLab APIのプロジェクト指定時に、数字のプロジェクトID、またはURL形式の namespace/project-name を使用します。パスに特殊文字やスペースが含まれる場合は、URLエンコーディングが必須です。スラッシュ（/）は %2F にエンコードする必要があります。 Before（エラーが起きるコード）： # スラッシュがエンコードされていない curl -H "PRIVATE-TOKEN: <your-token>" \ "https://gitlab.com/api/v4/projects/my-group/my-project/repository/commits" # 結果：404 Not Found After（修正後）： # スラッシュをURLエンコードする（%2F） curl -H "PRIVATE-TOKEN: <your-token>" \ "https://gitlab.com/api/v4/projects/my-group%2Fmy-project/repository/commits" # または数字のプロジェクトIDを使用 curl -H "PRIVATE-TOKEN: <your-token>" \ "https://gitlab.com/api/v4/projects/12345/repository/commits" 原因2：トークンの権限不足またはプロジェクトへのアクセス権限がない プライベートプロジェクトへのアクセスには、適切な権限を持つトークンが必要です。トークンが存在しない、有効期限が切れている、または該当プロジェクトへのアクセス権限がないメンバーが使用している場合、404が返されます。GitLabはセキュリティの観点から、権限がないリソースを404で返すため、403（Forbidden）と区別されません。 ...

エラーの概要 HTTP 409 Conflict エラーは、GitLab 上でリソースの状態が競合している場合に発生します。既に存在するブランチやタグ名での作成、MergeRequest のソースとターゲットブランチの重複、あるいは同名のグループ・プロジェクトの存在などが典型的な原因です。このエラーが発生すると、意図した操作がブロックされ、リソースの作成や更新が完了しません。 実際のエラーメッセージ例 GitLab API の 409 エラーは、以下のようなレスポンスで返されます。 { "message": "409 Conflict" } REST API でより詳細な情報が返される場合もあります。 { "message": { "base": ["Branch already exists"] } } また、GitLab UI でブランチ作成時に失敗する場合は、以下のような通知メッセージが表示されます。 Error: A branch with name 'main' already exists よくある原因と解決手順 原因 1：既に存在するブランチ名またはタグ名で作成しようとしている ブランチやタグの作成時に、既に同名のリソースが存在する場合、409 エラーが発生します。これは Git の基本的な制約で、同じ名前空間内で重複するブランチやタグを持つことはできません。API 経由でのブランチ作成や、CI/CD パイプライン内での自動ブランチ生成時に特に注意が必要です。 Before（エラーが起きるコード）： # 既に 'develop' ブランチが存在する場合、同じ名前で再度作成しようとする curl --request POST https://gitlab.example.com/api/v4/projects/<project-id>/repository/branches \ --header "PRIVATE-TOKEN: <your-token>" \ --data "branch=develop&ref=main" After（修正後）： # 事前にブランチの存在を確認してから作成する RESPONSE=$(curl --request GET https://gitlab.example.com/api/v4/projects/<project-id>/repository/branches/develop \ --header "PRIVATE-TOKEN: <your-token>" \ --write-out "\n%{http_code}") HTTP_CODE=$(echo "$RESPONSE" | tail -1) # ブランチが存在しない場合（404）のみ作成 if [ "$HTTP_CODE" = "404" ]; then curl --request POST https://gitlab.example.com/api/v4/projects/<project-id>/repository/branches \ --header "PRIVATE-TOKEN: <your-token>" \ --data "branch=develop&ref=main" else echo "Branch already exists" fi 原因 2：MergeRequest のソースブランチとターゲットブランチが同じになっている MergeRequest を作成する際、ソースブランチとターゲットブランチが同じ場合に 409 エラーが発生します。これは論理的に無意味な操作（自分自身へのマージ）であるため、GitLab はこれを防止しています。複雑なパイプライン設定や自動化スクリプト内で、ブランチ変数の設定ミスにより起こることがあります。 ...

エラーの概要 GitLabの422エラーは「Unprocessable Entity」を意味し、リクエスト自体は正しく到達したものの、送信されたデータが検証ルールを満たしていないことを示します。プロジェクト作成、マージリクエスト、イシューなどのAPI操作で頻繁に発生し、GitLabサーバー側がデータの内容を受け入れられない状態です。 実際のエラーメッセージ例 GitLabのAPI経由で発生した422エラーの典型的なレスポンスは以下のようなJSON形式です。 { "message": "422 Unprocessable Entity", "error": "Validation failed", "errors": { "title": ["can't be blank"], "description": ["is invalid"] } } ブラウザのWebUIで遭遇した場合のエラー表示例： 422 Unprocessable Entity Failed to create merge request: Title can't be blank よくある原因と解決手順 原因1：マージリクエストのタイトルが空白になっている マージリクエスト作成時にtitleフィールドが空文字列または省略されると、GitLabの検証ルールに違反して422エラーが発生します。GitLab APIではtitleが必須フィールドとして定義されており、どのような値でも良いわけではなく「空でない文字列」という最小限の検証を通す必要があります。 修正前（エラーが起きるコード）： curl --request POST \ --header "PRIVATE-TOKEN: <your-token>" \ "https://<your-gitlab-instance>/api/v4/projects/<project-id>/merge_requests" \ --data "source_branch=feature-branch&target_branch=main&title=" 修正後： curl --request POST \ --header "PRIVATE-TOKEN: <your-token>" \ "https://<your-gitlab-instance>/api/v4/projects/<project-id>/merge_requests" \ --data "source_branch=feature-branch&target_branch=main&title=Add new feature" 原因2：プロジェクト名がグループのルールに違反している グループレベルで名前の長さ制限や命名規則が設定されている場合、その規則に適合しないプロジェクト名で作成しようとすると422エラーが返されます。特に大規模な組織では、プロジェクト命名を統一するためにグループ管理者が検証ルールを配置していることがあります。 修正前（エラーが起きるコード）： curl --request POST \ --header "PRIVATE-TOKEN: <your-token>" \ "https://<your-gitlab-instance>/api/v4/projects" \ --data "name=ThisProjectNameIsWayTooLongAndViolatesGroupNameLengthRestrictions&namespace_id=<group-id>" 修正後： ...

エラーの概要 GitLab の 400 エラーは、「Bad Request」を意味し、GitLab API またはウェブインターフェースへのリクエストの形式や内容に誤りがある場合に発生します。これは、サーバーがリクエストを正しく解析できない、または必須情報が不足していることを示します。CI/CD パイプラインの実行時やプロジェクト管理操作の際に頻出するエラーです。 実際のエラーメッセージ例 API リクエストの場合： { "message": "400 Bad Request", "error": "Invalid JSON body", "error_description": "The request body could not be parsed as JSON" } CI/CD パイプライン実行時： ERROR: (ci::pipeline:creation) This project does not have CI enabled 400 Bad Request - The request body contains invalid fields よくある原因と解決手順 原因1：JSON リクエストボディの形式エラーまたは必須フィールドの欠落 GitLab API への POST/PUT リクエストで、JSON の形式が壊れているか、API が必須とするフィールドが含まれていません。特に issue 作成や merge request の更新時に頻発します。 Before（エラーが起きるコード）： curl -X POST "https://gitlab.example.com/api/v4/projects/<project_id>/issues" \ -H "PRIVATE-TOKEN: <token>" \ -H "Content-Type: application/json" \ -d '{ "title": "New Issue" "description": "Missing comma and required labels field" }' After（修正後）： ...

エラーの概要 GitLab で 401 Unauthorized エラーが発生する場合、クライアントからのリクエストが認証されていない、または認証情報が無効であることを示しています。GitLab API へのアクセス、Git クローン、パイプラインからのリソース取得など、認証が必要な操作全般で発生する可能性があります。このエラーが出た場合、提供されたトークンや認証情報を確認し、それらの有効性と形式を検証する必要があります。 実際のエラーメッセージ例 GitLab API レスポンス： { "message": "401 Unauthorized" } curl コマンドの出力： $ curl -H "Authorization: Bearer invalid-token" https://gitlab.example.com/api/v4/user {"message":"401 Unauthorized"} Git クローン時のエラー： $ git clone https://gitlab.example.com/group/project.git Cloning into 'project'... fatal: Authentication failed for 'https://gitlab.example.com/group/project.git/' よくある原因と解決手順 原因1：パーソナルアクセストークン（PAT）が無効または期限切れになっている GitLab のパーソナルアクセストークンには有効期限が設定でき、期限を過ぎたトークンでリクエストを送信すると 401 エラーが返されます。また、トークンを無効化した場合や、ユーザーアカウント設定で特定のスコープを失った場合も認証に失敗します。特に CI/CD パイプラインやスクリプトで長期間使用するトークンは、期限切れに気づきにくいため注意が必要です。 Before（エラーが起きるコード）： # 2024年1月に作成したトークンを2024年12月に使用しようとしている場合 $ curl -H "PRIVATE-TOKEN: glpat-xxxxxxxxxxxx" \ https://gitlab.example.com/api/v4/user # → 401 Unauthorized が返される After（修正後）： # GitLab UI で新しいパーソナルアクセストークンを生成 # User Settings → Access Tokens → Add new token # スコープ: api, read_user, read_repository などを選択 $ curl -H "PRIVATE-TOKEN: <your-gitlab-token>" \ https://gitlab.example.com/api/v4/user # → 200 OK で成功 原因2：Authorization ヘッダーの形式が誤っている GitLab API にアクセスする際、Authorization ヘッダーの形式が仕様と異なると認証失敗になります。Bearer トークンを使う場合と PRIVATE-TOKEN ヘッダーを使う場合で形式が異なり、特に古いドキュメントを参照している場合に混同しやすいです。また、トークン前後の空白や特殊文字の誤りも 401 の原因になります。 ...

エラーの概要 GitLab の 403 エラーは、認証済みのユーザーがプロジェクトやリソースへのアクセス権限を持たないときに返されるアクセス拒否エラーです。認証自体は成功していますが、実行しようとしたアクション（プッシュ、マージリクエストの作成、設定変更など）の権限がないことを示します。GitLab での権限管理はロールベースアクセス制御（RBAC）に基づいており、プロジェクトメンバーシップ、グループ設定、ブランチ保護ルールなどの複数の層で管理されるため、原因の特定には段階的な確認が必要です。 実際のエラーメッセージ例 Git コマンドライン実行時： $ git push origin feature-branch remote: GitLab: You are not allowed to push code to this project. fatal: unable to access 'https://gitlab.example.com/group/project.git/': The requested URL returned error: 403 GitLab Web UI のレスポンス： { "message": "403 Forbidden", "error": "You do not have permission to perform this action" } パイプラインや API 呼び出し時： $ curl -H "PRIVATE-TOKEN: <your-token>" https://gitlab.example.com/api/v4/projects/123/issues {"message":"403 Forbidden"} よくある原因と解決手順 原因1：プロジェクトメンバーのロール権限が不足している GitLab では、プロジェクトへのアクセスレベルが細分化されています。Guest（ゲスト）や Reporter（レポーター）ロールでは、コードのプッシュやマージリクエストの承認などの重要な操作ができません。ユーザーが必要な操作を実行しようとしても、割り当てられたロールに権限がなければ 403 エラーが発生します。 修正方法： GitLab の Web UI から、対象プロジェクトの Settings → Members に移動し、ユーザーのロールを Developer 以上に変更します。変更後、ユーザーはコードをプッシュできるようになります。 ...