CI/CD 스키마에 기여하기

요약

파이프라인 에디터는 CI/CD 스키마를 사용하여 CI/CD 구성 파일 작성 경험을 향상시킵니다. 에디터에서 작성 중인 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 스키마가 처음이라면, JSON 스키마 작업 방법에 대한 단계별 소개를 위해 이 가이드를 참고해보세요.

키워드 업데이트#

CI/CD 스키마는 app/assets/javascripts/editor/schema/ci.json에 있습니다. CI/CD 구성 파일 작성에 사용 가능한 모든 키워드가 포함되어 있습니다. 사용 가능한 모든 키워드의 포괄적인 목록은 CI/CD YAML 문법 참조를 확인하세요.

모든 키워드는 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 키 아래에 정의됩니다.

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

스키마 업데이트 가이드라인#

키워드 참조에 유연성을 높이기 위해 가능한 한 정의를 원자적으로 유지하세요. 예를 들어, workflow:rules는 rules 정의의 속성 중 일부만 사용합니다. rules 속성들은 각각의 정의를 가지고 있으므로 개별적으로 참조할 수 있습니다.
새 키워드를 추가할 때, 문서 내 키워드 정의 링크를 포함한 description을 추가하는 것을 고려하세요. 이 정보는 사용자가 키워드 위에 마우스를 올렸을 때 어노테이션에 표시됩니다.
각 속성에 대해 minimum, maximum, 또는 default 값이 필요한지 고려하세요. 일부 값은 필수일 수 있으며, 다른 경우에는 비워둘 수 있습니다. 비워두는 경우 정의에 다음을 추가할 수 있습니다:

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

스키마 테스트#

변경사항 확인#

CI/CD > 에디터로 이동합니다.
에디터에서 CI/CD 구성을 작성하고 스키마가 올바르게 검증하는지 확인합니다.

스펙 작성#

모든 CI/CD 스키마 스펙은 spec/frontend/editor/schema/ci에 있습니다. 레거시 테스트는 JSON으로 작성되어 있지만, 새로운 테스트는 모두 YAML로 작성하는 것을 권장합니다. 새로운 .gitlab-ci.yml 구성 파일을 추가하는 것처럼 작성할 수 있습니다.

테스트는 positive 테스트와 negative 테스트로 구분됩니다. Positive 테스트는 스키마 키워드를 의도한 대로 사용하는 CI/CD 구성 코드 스니펫입니다. 반대로 negative 테스트는 스키마 키워드가 올바르지 않게 사용된 예시를 제공합니다. 이러한 테스트는 스키마가 다양한 입력 예시를 예상대로 검증하는지 확인합니다.

ci_schema_spec.js는 스키마에 대해 모든 테스트를 실행하는 역할을 합니다.

테스트가 설정되는 방법에 대한 자세한 설명은 이 머지 리퀘스트에서 확인할 수 있습니다.

스키마 스펙 업데이트#

지정된 키워드에 대한 YAML 테스트가 없는 경우, yaml_tests/positive_tests와 yaml_tests/negative_tests에 새 파일을 생성하세요. 그렇지 않으면 기존 테스트를 업데이트할 수 있습니다:

다양한 종류의 입력을 검증하기 위해 positive 테스트와 negative 테스트를 모두 작성하세요.

새 파일을 생성한 경우, ci_schema_spec.js에서 해당 파일들을 import하고 각 파일을 해당하는 객체 항목에 추가하세요. 예를 들어:

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 테스트에 영향을 미치는 경우, 해당 테스트도 함께 업데이트하세요.