CI 파이프라인에서 YAML을 JSON으로 변환: 예상보다 더 자주 깨지는 이유

Source: Dev.to

왜 CI 파이프라인은 종종 JSON이 필요할까

많은 CI 도구는 입력으로 YAML만 받지만, 내부적으로는 설정을 JSON으로 변환하거나 전달합니다:

• API는 엄격한 JSON을 기대한다
• 스키마 검증기는 JSON을 기반으로 동작한다
• Helm은 YAML → JSON으로 렌더링한다
• 커스텀 빌드 단계는 설정을 JSON으로 직렬화한다

따라서 레포가 YAML을 사용하더라도, 하위 단계에서는 거의 항상 JSON이 관여합니다.

숨겨진 문제: YAML은 JSON보다 관대하다

YAML은 사람을 위해 설계되었기 때문에 미묘하지만 위험한 문제가 발생합니다.

1️⃣ 중복 키 (조용한 살인자)

YAML은 오류를 발생시키지 않고 중복 키를 허용합니다:

env:
  VAR1: value1
  VAR1: value2   # duplicate key

대부분의 YAML 파서는 첫 번째 값을 조용히 덮어씁니다. 변환 후 JSON은 다음과 같이 됩니다:

{
  "env": {
    "VAR1": "value2"
  }
}

파이프라인은 통과하지만 원래 의도는 사라집니다—CI 버그 중 가장 흔한 사례입니다.

2️⃣ “파싱”은 되지만 논리를 깨뜨리는 들여쓰기 오류

YAML 들여쓰기는 구조를 정의합니다. 겉보기엔 유효해 보이지만:

steps:
name: build
run:
  echo "Building"

파서에 따라 직렬화가 잘못되거나 변환 후 스키마 검증에 실패할 수 있습니다. CI 도구는 종종 YAML을 깊게 검증하지 않고 그대로 전달합니다.

3️⃣ 앵커와 별칭은 깔끔하게 번역되지 않는다

YAML은 재사용을 지원합니다:

defaults: &defaults
  timeout: 30
  retries: 2

job:
  <<: *defaults
  script: make test

변환 후 일부 도구는:

• 값을 인라인으로 삽입한다
• 앵커를 완전히 삭제한다
• 스키마 검증에 실패한다

JSON에는 앵커 개념이 없으므로 결과가 예측 불가능해집니다.

4️⃣ 데이터 타입이 경고 없이 바뀐다

YAML은 타입을 추측합니다:

enabled: yes

파서에 따라 다음과 같이 변환될 수 있습니다:

{
  "enabled": true
}

API가 문자열 "yes"를 기대한다면 호환성이 깨집니다.

일반적인 CI 변환 방법 (및 한계)

import yaml, json
json_data = json.dumps(yaml.safe_load(open("config.yaml")))

모범 사례: 변환 전에 검증하기

CI에서 YAML을 JSON으로 변환하기 전에:

1. 들여쓰기 검증
2. 중복 키 탐지
3. 데이터 타입 확인
4. 최종 JSON 출력 검사

이 검증을 API나 배포 단계에 도달하기 전에 수행하세요.

실전 디버깅 팁 (많이 도움이 됨)

CI 파이프라인이 변환 후 실패하면 다음을 시도해 보세요:

1. YAML을 엄격한 YAML → JSON 변환기에 붙여넣는다.
2. JSON 출력에서 다음을 확인한다:
   • 누락된 필드
   • 덮어쓰기된 키
   • 예상치 못한 불리언이나 숫자

편리한 브라우저 기반 도구는 jsonviewertool.com/yaml-to-json 입니다. 완전히 클라이언트‑사이드에서 동작하며 구조적 문제를 빠르게 찾아줍니다.

언제 변환을 완전히 피해야 할까?

가능하면:

• YAML을 처음부터 끝까지 유지한다 (예: Helm → Kubernetes).
• API와 연동될 때는 JSON으로 설정을 직접 정의한다.

변환은 의도적인 작업이어야 하며, 실수로 발생해서는 안 됩니다.

마무리 생각

YAML → JSON 변환 자체는 어렵지 않지만, 교묘하게 위험합니다. 대부분의 CI 실패 원인은:

• 오류를 발생시키지 않는다
• 검증을 통과한다
• 나중에 프로덕션 동작을 깨뜨린다

변환을 포맷팅 단계가 아니라 검증 단계로 다루세요. CI 파이프라인과 미래의 자신에게 큰 도움이 될 것입니다.

추가 읽을거리

• YAML vs JSON in APIs & CI pipelines
• Helm toJson pitfalls
• Duplicate key detection in YAML