ジョブ一つが抱えているもの

一言でいうと

ジョブはトップレベルのキー1つであり、その中で実行を生み出すのはscriptだけです。残りのキーはすべて、そのscriptを「いつ・どこで・何を持って」動かすかを決めるための飾りにすぎません。

なぜ必要なのか

パイプライン設定を初めて読む人が最も多く陥る思い違いは、キーの名前を覚えればよいと考えることです。しかし実際に行き詰まるのは文法ではなく構造です。stageを書いたのにジョブが見えない、imageを書いたのに別のイメージが使われる、同じ5行をジョブ6つにコピーしておいて1か所だけ直して事故になる。3つとも原因は同じです。何がジョブで何がジョブでないのか、そして値がどこから流れ込んでくるのかを知らないことです。

どう動くのか

トップレベルのマッピングのキー1つがジョブ1つです。ただし例外が3つあります。1つ目は、stages・variables・default・include・workflowは予約されたグローバル設定なので、ジョブではありません。2つ目は、名前がドットで始まるキー(.python-baseのようなもの)は隠しジョブなので、パイプラインに実行対象として載りません。3つ目は、値がマッピングでなければジョブになれません。

ジョブをジョブにするのはscriptです。scriptのないジョブは設定エラーで、GitLabはそのようなパイプラインをそもそも作りません。これは些細なルールではなく設計意図です。実行するものがないジョブは、存在する理由がありません。

残りのキーは3つにまとめておくと、覚えることが減ります。どこで動くかはimage・services・tagsが決めます。いつ動くかはstage・needs・rulesが決めます。何を持って動くかはvariables・artifacts・cache・before_scriptが決めます。ラボで触るキーはすべてこの3つの中にあります。

重複を減らす仕組みは2つあり、性格が異なります。defaultは、何も指定していないジョブに適用される下地の値です。グローバルで、ジョブが同じキーを直接書けばそちらが勝ちます。extendsは、指定した断片を深くマージして取り込みます。そのため、断片にbefore_scriptを置き、ジョブではscriptだけ別に書くような再利用ができます。似て見えるYAMLアンカー(&/*)はマージではなく、その場にそっくり展開するものです。1つのドキュメントの中でしか有効ではないため、includeで取り込んだファイルの間では使えません。そのため、実務のテンプレートはアンカーではなくextendsで書きます。

実務でよく起きる事故

一番多い事故はインデントです。scriptを1段深く入れると、それはジョブのキーではなく前のキーの下位項目になり、ジョブはscriptのないジョブになって、設定の検証で拒否されるか、一覧から静かに消えます。YAMLが何の文句も言わないことが、この事故を長引かせます。

2番目に多いのは、断片を作るときにドットを忘れることです。python-baseと書くと、それは引き継がれる断片ではなく、毎回のパイプラインで実際に動くジョブになります。たいていscriptがないので設定エラーで見つかりますが、断片にscriptを入れてある場合は、正常に動きながら意味のないジョブが1つ実行され続けます。

次のラボですること

設定1つを見ながら、何がジョブで何がジョブでないか、同じ名前の変数のうちどの値が勝つか、状況ごとにどのジョブが動くかを、自分で答えます。どれが下地の値でどれがマージなのかが分かれる地点を、そのファイルで見ることになります。