CI/CD 스키마에 기여하기
파이프라인 편집기는 CI/CD 구성 파일의 작성 경험을 향상시키기 위해 CI/CD 스키마를 사용합니다. CI/CD 스키마를 통해 편집기는 다음을 할 수 있습니다.
- 편집기에서 작성 중인 CI/CD 구성 파일의 내용을 유효성 검사합니다.
- 자동 완성 기능을 제공하고 사용 가능한 키워드를 제안합니다.
- 주석을 통해 키워드의 정의를 제공합니다.
우리의 CI/CD 구성 파일을 구성하기 위한 규칙과 키워드가 변경되면 CI/CD 스키마도 변경되어야 합니다.
JSON 스키마
CI/CD 스키마는 JSON Schema Draft-07 사양을 따릅니다. CI/CD 구성 파일은 YAML로 작성되지만, monaco-yaml을 사용하여 JSON으로 변환된 후 CI/CD 스키마에서 유효성을 검사합니다.
JSON 스키마에 익숙하지 않다면, 이 안내서를 확인하여 JSON 스키마 사용 방법에 대해 단계별 소개를 받아보세요.
키워드 업데이트
CI/CD 스키마는 app/assets/javascripts/editor/schema/ci.json에 있습니다. 여기에는 CI/CD 구성 파일을 작성하는 데 사용할 수 있는 모든 키워드가 포함되어 있습니다.
모든 키워드는 definitions 하위에 정의됩니다. 이러한 정의는 스키마 전체적으로 공통 데이터 구조를 공유하기 위해 참조로 사용됩니다.
예를 들어, 이는 retry 키워드를 정의합니다:
{
"definitions": {
"retry": {
"description": "작업을 재시도합니다. 간단한 정수나 객체 정의일 수 있습니다.",
"oneOf": [
{
"$ref": "#/definitions/retry_max"
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"max": {
"$ref": "#/definitions/retry_max"
},
"when": {
"description": "작업 재시도를 트리거할 에러 유형의 단일 또는 배열입니다.",
"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(부정적) 테스트로 나뉘어집니다. 긍정적 테스트는 스키마 키워드를 의도대로 사용하는 CI/CD 구성 코드 조각입니다. 반면, 부정적 테스트는 스키마 키워드가 잘못 사용되는 예제를 제공합니다. 이러한 테스트는 입력의 다양한 예제를 스키마가 예상대로 유효성을 검사하는지 확인합니다.
ci_schema_spec.js 파일은 스키마에 대한 모든 테스트를 실행합니다.
테스트가 어떻게 설정되었는지에 대한 자세한 설명은 이 Merge Request에서 찾을 수 있습니다.
스키마 스펙 업데이트
지정된 키워드에 대한 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합니다. 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, // 여기에 긍정적 테스트 추가 }), )('스키마가 %s를 유효성 검사합니다', (_, input) => { expect(input).toValidateJsonSchema(schema); }); }); describe('negative tests', () => { it.each( Object.entries({ CacheNegativeYaml, NewKeywordTestYaml, // 여기에 부정적 테스트 추가 }), )('스키마가 %s를 유효성 검사합니다', (_, input) => { expect(input).not.toValidateJsonSchema(schema); }); }); - 명령어
yarn jest spec/frontend/editor/schema/ci/ci_schema_spec.js를 실행하여 모든 테스트가 성공적으로 통과하는지 확인합니다.
스펙이 기존 키워드의 변경을 다루고 기존 JSON 테스트에 영향을 미친다면 해당 테스트도 업데이트하세요.
도움말