CI/CD 스키마 기여하기
pipeline editor는 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는 스키마에 대해 모든 테스트를 실행합니다.
이러한 테스트가 설정되는 방법에 대한 자세한 설명은 이 합병 요청에서 찾을 수 있습니다.
스키마 스펙 업데이트
지정된 키워드에 대한 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('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 테스트에 영향을 미친다면 해당 테스트도 업데이트하세요.
도움말