正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

CI/CDジョブ

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

CI/CD（継続的インテグレーションとデリバリー）ジョブは、GitLab CI/CDパイプラインの基本的な要素です。ジョブは.gitlab-ci.ymlファイル内で設定し、コードのビルド、テスト、デプロイなどのタスクを実行するためのコマンドのリストを指定します。

ジョブには次のような特徴があります:

  • Runner上で実行される（例: Dockerコンテナを実行環境として使用する）。
  • 他のジョブに依存せずに実行できる。
  • 完全な実行ログを含むジョブログがある。

ジョブは、YAMLキーワードを使用して定義します。これらのキーワードは、ジョブの実行に関するあらゆる側面を定義します。たとえば、次のことが可能です:

  • ジョブの実行方法とタイミングを制御する。
  • ジョブをステージと呼ばれるコレクションにグループ化する。ステージは順番に実行されますが、同じステージ内のジョブはすべて並列で実行できます。
  • 柔軟な設定を可能にするCI/CD変数を定義する。
  • ジョブの実行を高速化するキャッシュを定義する。
  • 他のジョブで利用できるようにファイルをアーティファクトとして保存する。

パイプラインにジョブを追加する

ジョブをパイプラインに追加するには、.gitlab-ci.ymlファイルに追加します。ジョブは次の条件を満たす必要があります:

次に例を示します:

my-ruby-job:
  script:
    - bundle install
    - bundle exec my_ruby_command

my-shell-script-job:
  script:
    - my_shell_script.sh

ジョブ名

以下のキーワードをジョブ名に使用することはできません:

  • image
  • services
  • stages
  • before_script
  • after_script
  • variables
  • cache
  • include
  • pages:deploy（deployステージ用に設定する場合）

さらに次の文字列は、引用符で囲めば有効ですが、パイプラインの設定が不明確になる可能性があるためジョブ名に使用するのは推奨されません:

  • "true":
  • "false":
  • "nil":

ジョブ名は255文字以下にする必要があります。

ジョブには一意の名前を使用してください。1つのファイル内で複数のジョブが同じ名前を持つ場合、パイプラインに追加されるのは1つのみであり、どのジョブが選ばれるのかを予測するのは困難です。インクルードされたファイルで同じジョブ名が1つ以上使用されている場合、パラメータはマージされます。

ジョブを非表示にする

ジョブを設定ファイルから削除せずに一時的に無効にするには、ジョブ名の先頭にピリオド（.）を追加します。非表示ジョブにはキーワードとしてscriptやtriggerを含める必要はありませんが、有効なYAML設定を含める必要があります。

次に例を示します:

.hidden_job:
  script:
    - run test

非表示ジョブはGitLab CI/CDによって処理されませんが、次のような再利用可能な設定のテンプレートとして使用できます:

ジョブキーワードのデフォルト値を設定する

defaultキーワードを使用すると、パイプライン内のすべてのジョブでデフォルトとして使用されるジョブキーワードと値を設定できます。

次に例を示します:

default:
  image: 'ruby:2.4'
  before_script:
    - echo Hello World

rspec-job:
  script: bundle exec rspec

パイプラインが実行されると、ジョブはデフォルトのキーワードを使用します:

rspec-job:
  image: 'ruby:2.4'
  before_script:
    - echo Hello World
  script: bundle exec rspec

デフォルトのキーワードと変数の継承を制御する

次の継承を制御できます:

次に例を示します:

default:
  image: 'ruby:2.4'
  before_script:
    - echo Hello World

variables:
  DOMAIN: example.com
  WEBHOOK_URL: https://my-webhook.example.com

rubocop:
  inherit:
    default: false
    variables: false
  script: bundle exec rubocop

rspec:
  inherit:
    default: [image]
    variables: [WEBHOOK_URL]
  script: bundle exec rspec

capybara:
  inherit:
    variables: false
  script: bundle exec capybara

karma:
  inherit:
    default: true
    variables: [DOMAIN]
  script: karma

この例では:

  • rubocop:
    • 継承する: なし。
  • rspec:
    • 継承する: デフォルトのimageとWEBHOOK_URL変数。
    • 継承not（しない）: デフォルトのbefore_scriptとDOMAIN変数。
  • capybara:
    • 継承する: デフォルトのbefore_scriptとimage。
    • 継承not（しない）: DOMAINとWEBHOOK_URL変数。
  • karma:
    • 継承する: デフォルトのimage、before_script、DOMAIN変数。
    • 継承not（しない）: WEBHOOK_URL変数。

パイプライン内のジョブを表示する

パイプラインにアクセスすると、そのパイプラインに関連するジョブを確認できます。

パイプライン内のジョブの順序は、パイプライングラフのタイプによって異なります。

個々のジョブを選択すると、そのジョブログが表示され、次の操作を行えます:

  • ジョブをキャンセルする。
  • ジョブが失敗した場合に再試行する。
  • ジョブが正常に完了した場合に再実行する。
  • ジョブログを消去する。

プロジェクトジョブを表示する

  • 提供形態: GitLab.com、GitLab Self-Managed

プロジェクトで実行されたジョブを表示するには、次の手順に従います:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. ビルド > ジョブを選択します。

ジョブのリストは、ジョブのステータス、ソース、名前、種類でフィルタリングできます。

名前によるフィルターは、過去30日間に作成されたジョブを返します。この保持期間は、UIとAPIのフィルタリングの両方に適用されます。

デフォルトでは、ビルドジョブのみが表示されるようにフィルタリングされています。トリガージョブを表示するには、フィルターをクリアし、種類 > トリガーを選択します。

種類フィルターは、プロジェクトジョブでのみ使用可能です。管理者エリアでは使用できません。

使用可能なジョブステータス

CI/CDジョブには次のステータスがあります:

  • canceled: ジョブは手動でキャンセルされたか、または自動的に中断されました。
  • canceling: ジョブはキャンセル中ですが、after_scriptが実行されています。
  • created: ジョブは作成されましたが、まだ処理されていません。
  • failed: ジョブの実行に失敗しました。
  • manual: ジョブを開始するには手動操作が必要です。
  • pending: ジョブはRunnerを待機するキューに入っています。
  • preparing: Runnerが実行環境を準備中です。
  • running: ジョブはRunnerで実行中です。
  • scheduled: ジョブはスケジュールされていますが、実行は開始されていません。
  • skipped: ジョブは、条件または依存関係のためにスキップされました。
  • success: ジョブは正常に完了しました。
  • waiting_for_resource: ジョブはリソースが利用可能になるまで待機しています。

ジョブのソースを表示する

GitLab CI/CDジョブに、CI/CDジョブを最初にトリガーしたアクションを示すsource属性が含まれるようになりました。この属性を使用すれば、ジョブがどのように開始されたかを追跡したり、特定のソースに基づいてジョブの実行をフィルタリングしたりできます。

利用可能なジョブソース

source属性には次の値が設定されます:

  • api: Jobs APIに対するREST呼び出しによって開始されたジョブ。
  • chat: GitLab ChatOpsを使用したチャットコマンドによって開始されたジョブ。
  • container_registry_push: コンテナレジストリのプッシュによって開始されたジョブ。
  • duo_workflow: GitLab Duo Agent Platformによって開始されたジョブ。
  • external: GitLabと統合された外部リポジトリ内のイベントによって開始されたジョブ。プルリクエストイベントは含まれません。
  • external_pull_request_event: 外部リポジトリ内のプルリクエストイベントによって開始されたジョブ。
  • merge_request_event: マージリクエストイベントによって開始されたジョブ。
  • ondemand_dast_scan: オンデマンドDASTスキャンによって開始されたジョブ。
  • ondemand_dast_validation: オンデマンドDAST検証によって開始されたジョブ。
  • parent_pipeline: 親パイプラインによって開始されたジョブ。
  • pipeline: ユーザーが手動でパイプラインを実行したことによって開始されたジョブ。
  • pipeline_execution_policy: トリガーされたパイプライン実行ポリシーによって開始されたジョブ。
  • pipeline_execution_policy_schedule: スケジュールされたパイプライン実行ポリシーによって開始されたジョブ。
  • push: コードプッシュによって開始されたジョブ。
  • scan_execution_policy: スキャン実行ポリシーによって開始されたジョブ。
  • schedule: スケジュールされたパイプラインによって開始されたジョブ。
  • security_orchestration_policy: スケジュールされたスキャン実行ポリシーによって開始されたジョブ。
  • trigger: 別のジョブまたはパイプラインによって開始されたジョブ。
  • unknown: 不明なソースによって開始されたジョブ。
  • web: ユーザーによってGitLab UIから開始されたジョブ。
  • webide: ユーザーによってWeb IDEから開始されたジョブ。

パイプラインビューで類似のジョブをグループ化する

類似のジョブが多数ある場合、パイプライングラフが長くなり、読みづらくなります。

類似のジョブは自動的にグループ化できます。ジョブ名が特定の形式で指定されている場合、（ミニグラフではない）標準のパイプライングラフでは、単一のグループに折りたたまれます。

パイプラインにグループ化されたジョブがあるかどうかは、再試行ボタンやキャンセルボタンの代わりにジョブ名の横に数値が表示されることでわかります。この数値は、グループ化されたジョブの数を示します。数値の上にカーソルを合わせると、すべてのジョブが正常に完了したか、失敗したジョブがあるかを確認できます。ジョブを選択すると展開されます。

複数のステージとジョブが表示されたパイプライングラフに、グループ化されたジョブのグループが3つ含まれています。

ジョブのグループを作成するには、.gitlab-ci.ymlファイルで、各ジョブ名を数値と次のいずれかで区切ります:

  • スラッシュ（/）。例: slash-test 1/3、slash-test 2/3、slash-test 3/3。
  • コロン（:）。例: colon-test 1:3、colon-test 2:3、colon-test 3:3。
  • スペース。例: space-test 0 3、space-test 1 3、space-test 2 3。

上記の記号はどれも同じように動作します。

次の例では、3つのジョブがbuild rubyというグループに含まれています:

build ruby 1/3:
  stage: build
  script:
    - echo "ruby1"

build ruby 2/3:
  stage: build
  script:
    - echo "ruby2"

build ruby 3/3:
  stage: build
  script:
    - echo "ruby3"

パイプライングラフには、3つのジョブを含むbuild rubyという名前のグループが表示されます。

ジョブは、左から右に数値を比較して並べ替えられます。通常、最初の数値はインデックス、2番目の数値は合計に使用します。

この正規表現: ([\b\s:]+((\[.*\])|(\d+[\s:\/\\]+\d+))){1,3}\s*\zは、ジョブ名を評価します。1つ以上の: [...]、X Y、X/Y、X\Yというシーケンスは、ジョブ名のend（末尾）からのみ削除されます。ジョブ名の先頭や途中に一致する部分文字列がある場合は削除されません。

ジョブを再試行する

ジョブは、完了後の最終ステータス（失敗、成功、キャンセル）に関係なく再試行できます。

ジョブを再試行すると、次のようになります:

  • 新しいジョブIDを持つ新しいジョブインスタンスが作成されます。
  • ジョブは、元のジョブと同じパラメータと変数で実行されます。
  • アーティファクトを生成するジョブの場合、新しいアーティファクトが作成され、保存されます。
  • 新しいジョブは、元のパイプラインを作成したユーザーではなく、再試行を開始したユーザーに関連付けられます。
  • 以前にスキップされた後続のジョブは、再試行を開始したユーザーに再割り当てされます。

ダウンストリームパイプラインをトリガーするトリガージョブを再試行すると、次のようになります:

  • トリガージョブは新しいダウンストリームパイプラインを生成します。
  • そのダウンストリームパイプラインも、再試行を開始したユーザーに関連付けられます。
  • ダウンストリームパイプラインは再試行時の設定で実行され、元の実行時とは異なる場合があります。

ジョブを再試行する

前提要件:

  • プロジェクトのデベロッパーロール以上を持っている必要があります。
  • ジョブがアーカイブされていない必要があります。

マージリクエストからジョブを再試行するには、次のようにします:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. マージリクエストから、次のいずれかを実行します:
    • パイプラインウィジェットで、再試行するジョブの横にある再実行（ retry ）を選択します。
    • パイプラインタブを選択し、再試行するジョブの横にある再実行（ retry ）を選択します。

ジョブログからジョブを再試行するには、次のようにします:

  1. ジョブのログページに移動します。
  2. 右上隅で、再実行（ retry ）を選択します。

パイプラインからジョブを再試行するには、次のようにします:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. ビルド > パイプラインを選択します。
  3. 再試行するジョブが含まれているパイプラインを見つけます。
  4. パイプライングラフで、再試行するジョブの横にある再実行（ retry ）を選択します。

パイプライン内の失敗またはキャンセルされたジョブをすべて再試行する

パイプライン内に失敗またはキャンセルされたジョブが複数ある場合、それらすべてを一度に再試行できます:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. 次のいずれかを実行します:
    • ビルド > パイプラインを選択します。
    • マージリクエストに移動し、パイプラインタブを選択します。
  3. 失敗またはキャンセルされたジョブを含むパイプラインに対して、Retry all failed or canceled jobs（失敗またはキャンセルされたすべてのジョブを再試行）（ retry ）を選択します。

ジョブをキャンセルする

未完了のCI/CDジョブをキャンセルできます。

ジョブをキャンセルした後の挙動は、ジョブのステータスとGitLab Runnerのバージョンによって異なります:

  • まだ実行を開始していないジョブの場合、ジョブはすぐにキャンセルされます。
  • 実行中のジョブの場合は、次のようになります:
    • GitLab Runner 16.10以降とGitLab 17.0以降の場合:
      1. ジョブはcancelingとしてマークされます。
      2. 現在実行中のコマンドは完了できます。ジョブのbefore_scriptまたはscriptの残りのコマンドはスキップされます。
      3. ジョブにafter_scriptセクションがある場合、常に開始され、完了まで実行されます。
      4. ジョブはcanceledとしてマークされます。
    • GitLab Runner 16.9以前かつGitLab 16.11以前の場合、after_scriptを実行せず、ジョブはすぐにキャンセルされ、canceledとマークされます。

after_scriptを待たずにジョブをすぐにキャンセルする必要がある場合は、強制キャンセルを使用します。

ジョブをキャンセルする

前提要件:

マージリクエストからジョブをキャンセルするには、次のようにします:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. マージリクエストから、次のいずれかを実行します:
    • パイプラインウィジェットで、キャンセルするジョブの横にあるキャンセル（ cancel ）を選択します。
    • パイプラインタブを選択し、キャンセルするジョブの横にあるキャンセル（ cancel ）を選択します。

ジョブログからジョブをキャンセルするには、次のようにします:

  1. ジョブのログページに移動します。
  2. 右上隅で、キャンセル（ cancel ）を選択します。

パイプラインからジョブをキャンセルするには、次のようにします:

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. ビルド > パイプラインを選択します。
  3. キャンセルするジョブが含まれているパイプラインを見つけます。
  4. パイプライングラフで、キャンセルするジョブの横にあるキャンセル（ cancel ）を選択します。

パイプラインで実行中のジョブをすべてキャンセルする

実行中のパイプライン内のすべてのジョブを一度にキャンセルできます。

  1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. 次のいずれかを実行します:
    • ビルド > パイプラインを選択します。
    • マージリクエストに移動し、パイプラインタブを選択します。
  3. キャンセルするパイプラインに対して、実行中のパイプラインをキャンセル（ cancel ）を選択します。

ジョブを強制的にキャンセルする

after_scriptの完了を待機しない場合、またはジョブが応答しなくなった場合は、強制的にキャンセルできます。強制的にキャンセルすると、ジョブのステータスがすぐにcancelingからcanceledに移行します。

ジョブを強制的にキャンセルすると、ジョブトークンが即座に失効します。Runnerがまだジョブの実行中でも、GitLabへのアクセス権を失います。Runnerはafter_scriptの完了を待たずにジョブを中断します。

前提要件:

  • プロジェクトのメンテナーロール以上が必要です。
  • ジョブはcancelingステータスである必要があります。そのためには以下が必要です:
    • GitLab 17.0以降。
    • GitLab Runner 16.10以降。

ジョブを強制的にキャンセルするには、次のようにします:

  1. ジョブのログページに移動します。
  2. 右上隅で、強制的にキャンセルを選択します。

失敗したジョブの問題を解決する

パイプラインが失敗した場合、または失敗が許可されている場合、原因を確認できる場所がいくつかあります:

  • パイプライン詳細ビューのパイプライングラフ。
  • マージリクエストページとコミットページのパイプラインウィジェット。
  • ジョブビュー（ジョブのグローバルビューと詳細ビュー）。

それぞれの場所で、失敗したジョブにカーソルを合わせると、失敗した理由を確認できます。

失敗したジョブと失敗の理由が表示されたパイプライングラフ。

ジョブの詳細ページでもジョブが失敗した理由を確認できます。

根本原因分析を使用する

GitLab Duo ChatのGitLab Duo根本原因分析を使用して、失敗したCI/CDジョブの問題を解決できます。

デプロイジョブ

デプロイジョブは、環境を使用するCI/CDジョブです。デプロイジョブとは、environmentキーワードとstart環境actionを使用するすべてのジョブを指します。デプロイジョブは、deployステージに配置する必要はありません。次のdeploy meジョブは、デプロイジョブの例です。action: startはデフォルトの動作で、説明のためにここでは定義していますが、省略しても構いません:

deploy me:
  script:
    - deploy-to-cats.sh
  environment:
    name: production
    url: https://cats.example.com
    action: start

デプロイジョブの動作は、古いデプロイジョブを防止や一度に1つのデプロイジョブのみを実行などのデプロイの安全性設定を使用して制御できます。