GitLab CIパイプラインで「Job failed (exit code 128)」というエラーに遭遇し、お困りではありませんか？ご安心ください、このエラーはGit操作の失敗を示す一般的なものであり、多くの場合、適切な手順を踏むことで解決できます。
この記事では、Windowsユーザー向けに、この問題の最も速い解決策から、主要な原因、そして恒久的な再発防止策までを、具体的かつ分かりやすく解説します。一つずつ確認していきましょう。
目次
1. GitLab CI: Job failed (exit code 128) とは？（概要と緊急度）
exit code 128 は、Gitコマンドの実行中に何らかの致命的なエラーが発生したことを示すコードです。GitLab CI/CDのコンテキストでこのエラーが発生した場合、GitLab Runnerがリポジトリをクローンしたり、フェッチしたり、プッシュしたりといったGit操作を実行しようとした際に失敗したことを意味します。
このエラーは、主に以下のようなGit操作に関連する問題で発生します。
- リポジトリへのアクセス権限がない、またはSSHキーなどの認証情報に問題がある
- リポジトリのURLが間違っている
- Runnerの環境内でGitリポジトリの状態（
.gitディレクトリ）が破損している
CI/CDパイプラインが停止するため、このエラーの緊急度は中〜高ですが、ほとんどの場合は単純な原因で解決可能です。落ち着いて、次のステップに進みましょう。
2. 【最速】今すぐ試すべき解決策
まずは、最も手軽で多くのケースで効果を発揮する解決策から試してみましょう。これにより、一時的な環境の問題やキャッシュの破損が原因であれば、すぐに解決する可能性があります。
解決策1：Runnerのキャッシュをクリアしてジョブを再実行する
GitLab Runnerは、ジョブの実行を高速化するためにキャッシュを使用することがあります。このキャッシュが破損したり、古い情報を含んでいたりすると、Git操作が失敗することがあります。Runnerのキャッシュをクリアしてジョブを再実行することで、クリーンな状態でリポジトリを再クローンさせることができます。
手順：
- GitLabのプロジェクトにアクセスします。
- サイドバーから 「Build」→「Pipelines」 を選択します。
- 失敗したパイプライン、または再実行したいジョブが含まれるパイプラインを探します。
- 対象のジョブの横にある「再実行」ボタン（通常は矢印のアイコン）をクリックします。
- ポップアップが表示されたら、「Retry job (Clear Runner caches)」 オプションを選択してジョブを再実行します。
この手順はGitLabのUIから実行するため、特別なコマンドは不要です。Runnerがクリーンな状態でリポジトリをクローンし直すため、多くの場合、このシンプルな手順で問題が解決します。
3. GitLab CI: Job failed (exit code 128) が発生する主要な原因（複数）
キャッシュクリアで解決しない場合、以下のいずれかの原因が考えられます。一つずつ確認し、適切な対処法を試してみてください。
- SSHキーまたは認証情報の問題:RunnerがGitLabリポジトリにアクセスするために使用するSSHキーが、GitLabに正しく登録されていない、有効期限切れ、パーミッションが不適切である、またはRunnerの環境に存在しない可能性があります。また、HTTPSを使用している場合は、パーソナルアクセストークンやユーザー名/パスワードに問題があるかもしれません。
確認方法（Windows環境での例）:
Runnerが動作しているサーバー（またはRunnerの実行ユーザーのコンテキスト）で、以下のPowerShellコマンドを実行してSSH接続をテストします。
ssh -T git@gitlab.com成功すると「Welcome to GitLab, @username!」のようなメッセージが表示されます。失敗する場合は、以下の手順でSSHキーの再生成とGitLabへの登録、
ssh-agentへのキー追加が必要です。# 1. 既存のSSHキーの存在を確認（公開鍵 .pub ファイルがあるか） Get-ChildItem ~/.ssh/*.pub # 2. 新しいSSHキーの生成（パスフレーズは任意ですが、CI/CD環境では空にすることが多いです） # コメントにはあなたのメールアドレスを推奨します ssh-keygen -t rsa -b 4096 -C "your_email@example.com" # 3. GitLabに公開鍵を登録（出力されたキーをコピーし、GitLabの「User Settings -> SSH Keys」に追加） Get-Content ~/.ssh/id_rsa.pub # 4. ssh-agent の起動とキーの追加（PowerShellの場合） # ssh-agent サービスが実行されているか確認 Get-Service ssh-agent | Select-Object Status, DisplayName # 停止している場合は起動設定を自動にし、サービスを開始 Set-Service ssh-agent -StartupType Automatic Start-Service ssh-agent # キーをssh-agentに追加 ssh-add ~/.ssh/id_rsa - リポジトリへのアクセス権限不足:Runnerが使用するユーザーアカウントや、デプロイトークン、アクセストークンに、対象リポジトリへの適切な読み取り権限が付与されていない可能性があります。特にプライベートリポジトリの場合に確認が必要です。
- Runnerの環境における
.gitディレクトリの破損:まれに、Runnerの作業ディレクトリ内の.gitディレクトリが何らかの原因で破損している場合があります。これはキャッシュクリアで解決することが多いですが、もし解決しない場合は、Runnerが使用している作業ディレクトリを直接クリーンアップする必要があるかもしれません（自己管理型Runnerの場合）。 - 不正なリポジトリURLまたはネットワークの問題:
.gitlab-ci.ymlファイルやRunnerの設定で指定されているリポジトリURLが間違っている、またはRunnerがGitLabインスタンスにアクセスできない（ファイアウォール、ネットワーク設定、プロキシ設定など）場合があります。 - Gitバージョンの問題:RunnerにインストールされているGitクライアントが古すぎる、または特定のバージョンに起因するバグがある可能性があります。Gitクライアントのアップデートを検討してください。
4. GitLab CIで恒久的に再発を防ぐには
一度解決しても、同じ問題が再発しないようにするための予防策を講じましょう。安定したCI/CDパイプラインは、これらの継続的な改善によって維持されます。
- CI/CD専用のSSHキーまたはアクセストークンの利用と管理:Runnerが個人のユーザーアカウントのSSHキーを使用するのではなく、GitLabの「Deploy Keys」や「Project/Group Access Tokens」を利用することを強く推奨します。これにより、権限管理が明確になり、個人のSSHキーの変更がCI/CDに影響を与えるリスクを減らせます。これらのキーは定期的に棚卸しし、有効期限が切れていないか確認しましょう。
.gitlab-ci.ymlのcache設定の最適化:不要なキャッシュは削除し、必要なキャッシュのみを適切に設定します。Gitリポジトリ自体をキャッシュに含めない（デフォルトでは含まれないはずですが）ことや、キャッシュのキーを適切に設定することで、古いキャッシュによる問題を防げます。常にクリーンな状態でリポジトリをクローンしたい場合は、
.gitlab-ci.ymlでGIT_STRATEGY: cloneを明示的に指定することも可能です。これにより、Runnerはジョブごとにリポジトリを新規にクローンします。variables: GIT_STRATEGY: clone # clone, fetch, none のいずれかを指定- Runnerの環境とGitバージョンの定期的なメンテナンス:Runnerが動作するOSや、インストールされているGitクライアント、Dockerなどの関連ツールを最新の状態に保つことで、既知のバグや脆弱性に起因する問題を回避できます。特に、Gitクライアントは最新の安定版にアップデートすることをお勧めします。
- 詳細なログの確認とモニタリング:ジョブが失敗した際には、GitLab CIのジョブログを注意深く確認する習慣をつけましょう。
exit code 128の前後に、より具体的なエラーメッセージが表示されていることがあります。自己管理型Runnerの場合は、Runner自体のシステムログ（例: Windowsイベントログ）も確認することで、ネットワークやリソースの問題など、根本原因の特定に役立ちます。
これらの対策を講じることで、「Job failed (exit code 128)」エラーの再発リスクを大幅に低減し、安定したCI/CDパイプラインを維持できるでしょう。諦めずに、一つずつ確認してください。