CI/CDスキーマに貢献する者

パイプラインエディタはCI/CDスキーマを使用し、CI/CD設定ファイルの作成者を強化します。CI/CDスキーマにより、エディタは以下のことができます：

CI/CD 設定ファイルがエディタに書き込まれているときに、その内容を検証します。
オートコンプリート機能を提供し、利用可能なキーワードを提案します。
アノテーションによるキーワードの定義の提供。

CI/CD設定ファイルのルールやキーワードが変わるにつれて、CI/CDスキーマも変わっていくはずです。

JSONスキーマ

CI/CD スキーマはJSON Schema Draft-07仕様に従っています。CI/CD設定ファイルはYAMLで書かれていますが、CI/CDスキーマによって検証される前にmonaco-yaml 。

もしJSONスキーマに慣れていないのであれば、JSONスキーマの使い方をステップバイステップで紹介しているこのガイドをチェックしてみてください。

キーワードの更新

CI/CDスキーマはapp/assets/javascripts/editor/schema/ci.jsonにあります。これにはCI/CD設定ファイルの作成者に利用可能な全てのキーワードが含まれています。利用可能なすべてのキーワードの包括的なリストについては、キーワードリファレンスを確認してください。

すべてのキーワードはdefinitions で定義されています。これらの定義は、スキーマ全体で共通のデータ構造を共有するための参照として使用されます。

例えば、これはretry キーワードを定義しています：

{
  "definitions": {
    "retry": {
      "description": "Retry a job if it fails. Can be a simple integer or object definition.",
      "oneOf": [
        {
          "$ref": "#/definitions/retry_max"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "max": {
              "$ref": "#/definitions/retry_max"
            },
            "when": {
              "description": "Either a single or array of error types to trigger job retry.",
              "oneOf": [
                {
                  "$ref": "#/definitions/retry_errors"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/retry_errors"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

この定義では、retry キーワードは、job_template 定義のプロパティでもあり、default グローバルキーワードのプロパティでもあります。パイプラインの動作を設定するグローバルキーワード (workflow やstagesなど) は、一番上のプロパティキーの下に定義されます。

{
  "properties": {
    "default": {
      "type": "object",
      "properties": {
        "retry": {
          "$ref": "#/definitions/retry"
        },
      }
    }
  },
  "definitions": {
    "job_template": {
      "properties": {
        "retry": {
          "$ref": "#/definitions/retry"
        }
      },
    }
  }
}

スキーマ更新のガイドライン

キーワードの参照に柔軟性を持たせるため、可能な限り定義をアトミックに保ってください。例えば、workflow:rules は、rules 定義の rules中でプロパティのサブセットのみを使用しています。rules プロパティには rulesそれぞれ定義があるので、個別に参照することができます。
新しいキーワードを追加するときは、description 、ドキュメントのキーワード定義へのリンクを追加することを検討してください。この情報は、ユーザーがキーワードの上にカーソルを置くと、注釈に表示されます。
各プロパティについて、minimum 、maximum 、default の値が必要かどうかを検討します。いくつかの値は必須かもしれませんし、他の値では空白を設定することができます。空白の場合、定義に以下を追加できます：

{
  "keyword": {
    "oneOf": [
      {
        "type": "null"
      },
      ...
    ]
  }
}

スキーマのテスト

変更の検証

CI/CD>Editorに移動します。
CI/CD設定をエディタに記述し、スキーマがそれを正しく検証することを確認します。

仕様を書く

CI/CD スキーマの仕様はすべてspec/frontend/editor/schema/ciにあります。レガシーなテストは JSON ですが、新しいテストはすべて YAML で書くことを推奨します。あたかも新しい.gitlab-ci.yml 設定ファイルを追加するように書くことができます。

テストはポジティブなテストとネガティブなテストに分離されます。ポジティブテストはスキーマキーワードを意図したとおりに使う CI/CD 設定コードのスニペットです。逆に、ネガティブテストはスキーマキーワードが誤って使われている例を示します。これらのテストは、スキーマが異なる入力例を期待通りに検証することを保証します。

ci_schema_spec.js は、スキーマに対してすべてのテストを実行する責任を負います。

テストがどのように設定されるのかについての詳細な説明は、このマージリクエストにあります。

スキーマ仕様の更新

指定したキーワードの YAML テストが存在しない場合、yaml_tests/positive_tests とyaml_tests/negative_tests に新しいファイルを作成します。そうでなければ、既存のテストを更新できます：

異なる種類の入力をバリデートするために肯定的なテストと否定的なテストの両方を書きます。

新しいファイルを作成した場合は、ci_schema_spec.js でインポートし、各ファイルを対応するオブジェクトエントリに追加します。例えば

import CacheYaml from './yaml_tests/positive_tests/cache.yml';
import CacheNegativeYaml from './yaml_tests/negative_tests/cache.yml';
   
// import your new test files
import NewKeywordTestYaml from './yaml_tests/positive_tests/cache.yml';
import NewKeywordTestNegativeYaml from './yaml_tests/negative_tests/cache.yml';
   
describe('positive tests', () => {
  it.each(
    Object.entries({
      CacheYaml,
      NewKeywordTestYaml, // add positive test here
    }),
  )('schema validates %s', (_, input) => {
    expect(input).toValidateJsonSchema(schema);
  });
});
   
describe('negative tests', () => {
  it.each(
    Object.entries({
      CacheNegativeYaml,
      NewKeywordTestYaml, // add negative test here
    }),
  )('schema validates %s', (_, input) => {
    expect(input).not.toValidateJsonSchema(schema);
  });
});

コマンドyarn jest spec/frontend/editor/schema/ci/ci_schema_spec.js を実行し、すべてのテストが正常にパスすることを確認します。

仕様が既存のキーワードの変更を対象としており、それがレガシー JSON テストに影響する場合は、それらも更新してください。

CI/CDスキーマに貢献する者

JSONスキーマ

キーワードの更新

スキーマ更新のガイドライン

スキーマのテスト

変更の検証

仕様を書く

スキーマ仕様の更新

Help & feedback

Docs

Product

Feature availability and product trials

Get Help