YAML 구문 변경 리뷰 가이드
GitLab v19.6요약
CI/CD YAML 키워드를 추가하거나 수정하는 머지 리퀘스트를 리뷰할 때 이 체크리스트를 사용하여 사양, 문서, 테스트가 완전한지 확인합니다. 키워드가 파일 또는 디렉터리 경로를 받는 경우: 기존 키워드 이름을 하위 키워드로 추가하는 경우(예: 다른 키워드 안에 include:를 하위 키워드로 추가):
CI/CD YAML 키워드를 추가하거나 수정하는 머지 리퀘스트를 리뷰할 때 이 체크리스트를 사용하여 사양, 문서, 테스트가 완전한지 확인합니다.
리뷰 체크리스트#
경로 기반 키워드#
키워드가 파일 또는 디렉터리 경로를 받는 경우:
동작#
- glob 패턴을 지원하는지 확인합니다. 지원하는 패턴을 문서화합니다:
*,**,? - 상대 경로, 절대 경로, 중첩 경로를 지원하는지 확인합니다.
- 상대 경로의 기준 디렉터리가 무엇인지 확인합니다.
- 심볼릭 링크를 따라가는지 확인합니다.
- 경로가 존재하지 않을 때 어떻게 동작하는지 확인합니다.
사양 및 테스트#
- 모든 경로 처리 동작이 스펙으로 다뤄지는지 확인합니다.
- 엣지 케이스(빈 경로, 특수 문자, 매우 긴 경로)가 테스트되는지 확인합니다.
- 의도적으로 지원하지 않는 동작(예: glob 미지원)이 있다면 다음을 확인합니다.
- 제한 사항으로 명시적으로 문서화되어 있는지 확인합니다.
- 현재 동작을 문서화하는 스펙으로 다뤄지는지 확인합니다. (제한 사항이 나중에 의도적으로든 아니든 제거되면, 실패하는 테스트가 이를 알려 현재 동작에 의존하는 파이프라인에 대한 호환성을 깨는 변경을 막습니다.)
변수#
동작#
- 이 컨텍스트에서 변수가 확장되는지 확인합니다.
- 중첩 변수 확장을 지원하는지 확인합니다.
- 확장이 구성 파싱(Rails/백엔드) 중에 일어나는지, 아니면 변수가 확장되지 않은 채 러너로 전달되기 때문에 일어나는 것인지 확인합니다.
사양 및 테스트#
- 확장 유형과 기타 관련 세부 정보 같은 변수 확장 동작이 문서 표에 명시되어 있는지 확인합니다.
- 긍정(확장이 작동함) 사례와 부정(확장이 작동하지 않음) 사례를 모두 명시적으로 테스트하는지 확인합니다.
- 중첩 확장이 작동하지 않는다면, 향후 실수로 활성화되는 것을 막는 스펙이 있는지 확인합니다. 중첩 확장이 실수로 활성화되면 현재 동작에 의존하는 파이프라인을 사용하는 사용자에게 호환성을 깨는 변경이 될 수 있습니다.
- YAML 참조 페이지의 키워드 문서가 작동하는 것과 작동하지 않는 것을 명시하는지 확인합니다.
키워드 재사용 및 일관성#
기존 키워드 이름을 하위 키워드로 추가하는 경우(예: 다른 키워드 안에
include:를 하위 키워드로 추가):
동작#
- 원래 키워드의 모든 기능과 하위 키워드를 지원하는지 확인합니다.
- 그렇지 않다면 제한 사항이 명시적으로 문서화되어 있는지 확인합니다.
- 사용자가 하위 키워드에서 지원되지 않는 원래 키워드의 기능을 사용하려고 하면 어떻게 되는지 확인합니다. (기대 사항과 허용 가능한 실패 방식은 이 코멘트를 참고합니다.)
- 지원되지 않는 구문을 사용할 때 명확한 오류 메시지가 표시되는지 확인합니다.
사양 및 테스트#
- 이 하위 키워드가 원래 키워드의 모든 기능을 지원하지 않는다면, 지원되지 않는 기능이 문서화되어 있는지 확인합니다.
- 유효성 검사가 호환되지 않는 구문을 구체적인 오류와 함께 제대로 거부하는지 확인합니다.
- 사용자가 하위 키워드가 원래 키워드와 동일하게 작동한다고 가정하는 시나리오를 테스트가 다루는지 확인합니다.
조합 가능성#
키워드가 CI 조합 옵션과 함께 사용될 때 어떻게 동작하는지 확인합니다.
동작#
- YAML 앵커 - 기본 YAML 기능이며 보통 문제가 되지 않습니다.
-
!reference태그 - 사용자 지정 확장이며 예상치 못한 동작의 매우 빈번한 원인입니다.- 키워드 안이나 그 아래에서 사용할 때
!reference태그가 작동하는지 확인합니다. -
!reference태그로 가져온 섹션에서 사용할 때 키워드가 작동하는지 확인합니다.
- 키워드 안이나 그 아래에서 사용할 때
- include
- 키워드를 모든 유형의 include에서 사용해도 되는지 확인합니다. (예: 키워드를 컴포넌트에서 사용하지 않아야 할 이유가 있는지.)
- include된 파일에서 키워드를 사용할 때의 의미가 고려되었는지 확인합니다. (예:
include:project:로 include된 파일에서 사용되는include:local:은 무엇을 의미하는지 - 두 프로젝트 중 어느 쪽이 로컬로 간주되는지.)
-
extends- 해시는 깊은 병합(deep-merge)하지만 배열은 대체하므로 목록을 받는 키워드에서는 예상 밖의 결과가 나올 수 있습니다.- 작업이
extends를 사용할 때 키워드가 예상대로 병합되는지 확인합니다.
- 작업이
사양 및 테스트#
-
!reference태그 동작이 문서화되고 테스트되는지 확인합니다. -
include:동작이 문서화되고 테스트되는지 확인합니다. -
extends:병합 동작이 문서화되고 테스트되는지 확인합니다. - 유효성 검사가 원치 않는
!reference태그와include:사용을 제대로 거부하는지 확인합니다. - 스펙이 의도적으로 지원하지 않는 조합 가능성을 고려하는지 확인합니다.
성능 및 사용 제한#
제한이 없는 사용 차원은 결국(대개 의도치 않게) 대규모로 악용되어, 호환성을 깨는 변경 없이는 해결하기 어려운 성능 문제를 일으킵니다. 모든 키워드는 제품에 포함되기 전에 관련 제한을 갖춰야 합니다.
- 관련된 모든 차원에 제한이 적용되어 있는지 확인합니다.
- 문자열/값의 길이
- 목록/배열의 항목 수
- 제한이 문서화되어 있는지 확인합니다.
- 제한 문서가 제한을 높일 때의 잠재적인 성능 영향을 설명하는지 확인합니다.
문서 및 사양 완전성#
- 문서화된 모든 동작이 스펙과 테스트로 다뤄지는지 확인합니다.
- 구현된 모든 동작이 문서화되어 있는지 확인합니다.
- 유효성 검사 오류가 구체적이고 실행 가능한지 확인합니다.
- JSON 스키마를 통한 유효성 검사가 백엔드의 유효성 검사와 일관되는지 확인합니다.
- 구문 참조가 새로 추가되거나 변경된 키워드로 업데이트되었는지 확인합니다.
- 예시가 일반적인 사용 사례를 다루는지 확인합니다.
- 제한 사항과 주의할 점이 명확하게 강조되어 있는지 확인합니다.
CI 구문/처리 변경을 위한 기능 플래그#
CI YAML 파싱에 영향을 주는 변경은 기능 플래그 뒤에 두어야 합니다. 플래그는 제거되기 전에 한 마일스톤 동안 기본적으로 활성화되어 있어야 합니다. 이는 GitLab Self-Managed와 Dedicated 사용자가 예상치 못한 부작용이 생겼을 때 언제든 원래 동작으로 되돌릴 수 있도록 하기 위한 것입니다.
흔한 함정#
rules:exists에서는 중첩 변수 확장이 없음#
GitLab 이슈 #411344:
VAR1: $VAR2가 rules:exists에서 확장되지 않았습니다. 이 사실이 명확하게 문서화되어 있지 않았고,
애초에 지원할 계획이 없었을 수도 있는데도
사용자는 이를 버그로 인식했습니다.
교훈: 범위를 의도적으로 정하고, 사용자 기대는 항상 최대치를 기본으로 한다는 점을 고려합니다.
include 키워드 오타가 조용히 무시됨#
GitLab 이슈 #549736:
file 대신 files를 사용하면 유일한 include가 아닌 경우 조용히 무시되어,
잘못된 YAML이 예상치 못한 결과와 함께 실행될 수 있습니다.
교훈: 테스트에서 일반적인 키워드 조합과 실제 사용 사례를 고려합니다. include 하나만 확인하는 명시적인 테스트가 있더라도 이 문제는 잡아내지 못합니다.
캐시 키 파일의 glob 패턴이 깨짐#
GitLab 이슈 #572701:
cache:key:files의 와일드카드 패턴이 작동하지 않게 되고 대신
default 키로 대체되어 캐시가 잘못 재사용되었습니다.
교훈: 기존 키워드를 변경할 때는 가능한 모든 사용 패턴이 스펙으로 다뤄지는지 확인하고, 변경하기 전에 빈틈을 메웁니다.
도움 받기#
- 질문:
#g_pipeline-authoringSlack 채널 - 리뷰 요청: MR에서
@gitlab-org/maintainers/cicd-verify를 멘션합니다 - 이 가이드에 대한 피드백: 이 페이지를 업데이트하는 머지 리퀘스트를 엽니다