CI/CD 스키마에 기여하기

요약

파이프라인 편집기는 CI/CD 설정 파일의 작성 경험을 높이기 위해 CI/CD 스키마를 사용합니다. CI/CD 설정 파일을 구성하는 규칙과 키워드가 바뀌면 CI/CD 스키마도 함께 바뀌어야 합니다. CI/CD 스키마는 JSON Schema Draft-07 명세를 따릅니다.

파이프라인 편집기는 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 > 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 하고 각 파일을 대응하는 객체 항목에 추가합니다. 예시는 다음과 같습니다:

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 테스트에 영향을 준다면 해당 테스트도 함께 업데이트합니다.