GitLab・CI/CD パイプライン・パイプラインとジョブの API・2026年10月24日に確認

GitLab がパイプラインやジョブを断った理由

API で新しいパイプラインを始めるとき（POST /projects/:id/pipeline）、そのプロジェクトでパイプラインを作ること自体があなたのアカウントに許されていなければ 403、それ以外の理由なら 400 で、理由は message.base に入ります。ジョブの再実行・取り消し・実行は、それぞれ別の答え方をします。以下はすべて GitLab のソース（lib/api/ci/pipelines.rb・lib/api/ci/jobs.rb・パイプラインを作る手順）を 2026年10月24日に読んで確かめたものです：

HTTP/1.1 400 Bad Request

{"message":{"base":["Reference not found"]}}

新しいパイプライン：400

GitLab が確かめる順に：

• You do not have sufficient permission to run a pipeline on 'main'. Please select a different branch or contact your administrator for assistance.（和訳：「main」でパイプラインを実行する権限がありません。別のブランチを選ぶか、管理者に相談してください）：保護されたブランチで、あなたのアカウントにそこへのマージか push が許されていません（保護されたタグなら、そのタグを作ることが許されていません）。GitLab の説明では、保護されたブランチでパイプラインを実行する・手動のジョブを実行する・ジョブを再実行や取り消しすることは、そのブランチにマージか push ができる人にだけ許されます。
• Ref is ambiguous：その名前のブランチとタグが両方あります。Reference not found：その名前のブランチもタグもプロジェクトにありません。Commit not found：そのコミットが見つかりません。
• Insufficient permissions to set pipeline variables：変数を付けたのに、あなたの役割がプロジェクトのパイプライン変数を使える最小の役割に届いていません。パイプライン変数を使える役割へ。
• Missing CI config file：そのブランチに .gitlab-ci.yml（またはプロジェクトの CI/CD の設定で指定したファイル）がありません。
• 設定の誤り：.gitlab-ci.yml が検証に通らないときは、GitLab が見つけた最初の誤りがそのまま文になります。
• The pipeline did not run. Review the workflow:rules configuration for the pipeline.（和訳：パイプラインは実行されませんでした。パイプラインの workflow:rules の設定を見直してください）：workflow:rules がパイプラインごと外しました。GitLab 17.2 以前は Pipeline filtered out by workflow rules. でした。
• The resulting pipeline would have been empty. Review the rules configuration.（和訳：できるパイプラインは空になるところでした。rules の設定を見直してください）：ジョブの rules が全部のジョブを外したので、実行するものがありません。.pre と .post のステージのジョブだけでは、パイプラインとみなされません。GitLab 17.3〜19.2 は文の終わりが for the relevant jobs.、17.2 以前は Pipeline will not run for the selected trigger. The rules configuration prevented any jobs from being added to the pipeline. でした。

画面では、rules の 2 つの文に説明へのリンクが付きます。API では、ただの文として届きます。

新しいパイプライン：403

{"message":"403 Forbidden"}：プロジェクトでのあなたの役割では、パイプラインを作れません。api の権限が無いトークンも 403 で断られますが、そのときの答えには insufficient_scope と書いてあります。足す権限の見つけ方へ。

ジョブの再実行・取り消し・実行

• パイプラインの再実行（POST …/pipelines/:id/retry）は、失敗したジョブと取り消されたジョブをもう一度実行します。403 Forbidden：あなたのアカウントにパイプラインの更新か、そのジョブの再実行が許されていません（保護されたブランチなど）。今の GitLab のソースでは、ほかに 2 つあります。409 Pipeline is already being retried（同じパイプラインの別の再実行がまだ進んでいる）と、409 Error updating stale job（再実行の途中でジョブが変わった）です。
• ジョブの再実行（POST …/jobs/:id/retry）：403 Forbidden - Job is not retryable は、あなたのアカウントではなくジョブの側の理由です。ソースでは、再実行できるのは成功・失敗・取り消しで終わったジョブで、すでに再実行されておらず、アーカイブされておらず、デプロイが却下されていないものだけです。つまり、まだ終わっていない、誰かがもう再実行した（いちばん新しい実行を再実行する）、インスタンスのアーカイブの設定より古い、のどれかです。理由の付かない 403 Forbidden は、上と同じくアカウントの側です。
• 手動のジョブの実行（POST …/jobs/:id/play）：400 Unplayable Job：手動か遅延のジョブではない、アーカイブされている、または実行待ちでも終わってもいない、のどれかです。
• 取り消しは、パイプラインでもジョブでも、取り消すものが無くても 200 を返し、今のままのパイプラインかジョブを答えます。パイプラインについてはソースにそう注記があり、のちの版の API でエラーを返す予定です（gitlab-org/gitlab#519143）。答えの状態を見てください。
• 回数の上限：今のソースでは、再実行・取り消し・実行に回数の上限があります。超えると 429 です。ジョブと取り消しでは、待つ秒数を Retry-After のヘッダーでも送ります。

直し方

• Reference not found：ブランチかタグの名前を確かめる。手元のクローンにしか無いブランチなら、先に push する。
• 保護されたブランチで許されていない：メンテナーに頼むか、Settings > Repository > Protected branches で誰がそのブランチにマージ・push できるかを見る。
• rules の文：この種類のパイプラインに対する rules を見る。API で始めたパイプラインの CI_PIPELINE_SOURCE は api（画面の New pipeline からなら web）なので、push や merge_request_event だけを許す rules では外れます。
• Missing CI config file：そのブランチに .gitlab-ci.yml を足すか、プロジェクトの CI/CD の設定のファイル名を確かめる。
• Job is not retryable：更新して、そのジョブのいちばん新しい実行を見る。まだ動いていれば、終わるのを待つ。
• 再実行の 409：別の再実行が終わるのを待ち、更新してから、まだ失敗しているものを再実行する。
• 429：少し待ってからやり直す。Retry-After が届いていれば、その秒数だけ待つ。

IntelliJ IDEA で GitLab のパイプラインを見るなら

Lesstep の Pipeline Inbox for GitLab CI は、JetBrains IDE（2024.1 以降）のプラグインです。GitLab のプロジェクトのパイプラインをジョブとログといっしょに一覧にし、Pro では再実行・取り消し・実行ができます。ジョブの一覧では、GitLab ができると言うところにだけ再実行と実行を出します。GitLab が新しいパイプラインを始めないときは、上の rules の文のような GitLab の理由を出したまま、ダイアログを閉じません。ほかの操作を断られたときは、GitLab の文を添えてそう言います。403 なら、役割か保護されたブランチの設定（1.0.21 からは保護された環境も）が許していない可能性がある、と。1.0.21 からは、GitLab があなたのアカウントに実行を認めていない手動ジョブでは実行を押せなくします。回数の上限なら、1 分待つように、と（1.0.21 からは、GitLab がそれより長く待つように言うときは、また使える時刻を）。1.0.15 からは、403 の「Job is not retryable」では代わりに、GitLab がそのジョブをもう一度実行しないことと、更新して最新の実行を見るように言います。見るのは無料、再実行・取り消し・実行は Pro（月 US$1.50・30日間の無料試用つき）です。画面は日本語です。

GITLAB は GitLab Inc. の商標、IntelliJ IDEA は JetBrains s.r.o. の商標です。このページは GitLab Inc.・JetBrains のいずれとも提携しておらず、承認も受けていません。

ほかに：GitLab の「Insufficient permissions to set pipeline variables」 · GitLab のジョブのログの断り（403・404） · GitLab のジョブが詰まった・時間切れで落とされた · GitLab の「You are not authorized to run this manual job」 · GitLab のパイプラインがジョブ0件で失敗 · GitLab の「insufficient_scope」 · GitLab の 401「invalid_token」 · GitLab の 404「Project Not Found」 · GitLab の 404「Group Not Found」 · JetBrains の IDE で GitLab のパイプラインを見る · English