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 아래에 정의됩니다. 우리는 이러한 정의를 CI/CD 스키마 전반에 걸쳐 공통 데이터 구조를 공유하기 위한 참조로 사용합니다.
예를 들어, 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 구성 파일을 추가하는 것처럼 작성할 수 있습니다.
테스트는 긍정적 테스트와 부정적 테스트로 나뉩니다. 긍정적 테스트는 스키마 키워드를 의도한 대로 사용하는 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 NewKeywordTestYaml from './yaml_tests/positive_tests/cache.yml'; import NewKeywordTestNegativeYaml from './yaml_tests/negative_tests/cache.yml'; describe('긍정적 테스트', () => { it.each( Object.entries({ CacheYaml, NewKeywordTestYaml, // 여기 긍정적 테스트 추가 }), )('스키마가 %s를 검증합니다', (_, input) => { expect(input).toValidateJsonSchema(schema); }); }); describe('부정적 테스트', () => { 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 테스트에 영향을 미치는 경우, 해당 테스트도 업데이트합니다.
도움말