CI/CD 스키마에 기여하기
파이프라인 편집기는 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 하위에 정의됩니다. 이러한 정의를 공유하기 위해 키워드 자료 구조를 참조(reference)로 사용합니다.
예를 들어, 다음은 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, // 여기에 양수 테스트를 추가하세요 }), )('schema validates %s', (_, input) => { expect(input).toValidateJsonSchema(schema); }); }); describe('negative tests', () => { it.each( Object.entries({ CacheNegativeYaml, NewKeywordTestYaml, // 여기에 음수 테스트를 추가하세요 }), )('schema validates %s', (_, input) => { expect(input).not.toValidateJsonSchema(schema); }); }); - 명령어
yarn jest spec/frontend/editor/schema/ci/ci_schema_spec.js를 실행하고 모든 테스트가 성공적으로 통과되는지 확인하십시오.
스펙이 기존 키워드의 변경사항을 다루고 기존 JSON 테스트에 영향을 미치는 경우, 해당 테스트도 업데이트하십시오.
도움말