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": "작업이 실패한 경우 다시 시도합니다. 간단한 정수 또는 객체 정의가 될 수 있습니다.",
"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 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 테스트에 영향을 미치는 경우에는 해당 내용을 업데이트하세요.
도움말