YAML 들여쓰기 오류로 CI 배포가 실패하는 이유
GitHub Actions나 GitLab CI 설정 파일을 살짝 고치고 커밋했을 뿐인데 배포가 실패했다는 메시지를 받은 경험이 있을 것입니다. 코드 diff를 아무리 들여다봐도 명령어 한 글자 바뀐 게 없는데, 실제 원인은 눈에 잘 안 보이는 스페이스 한 칸인 경우가 많습니다. YAML은 중괄호 대신 들여쓰기 칸 수로 계층을 구분하는 문법이라, 공백 하나도 그 자체로 문법의 일부이기 때문입니다.
요약 ① YAML은 중괄호나 콤마 대신, 줄바꿈과 들여쓰기 칸 수만으로 계층을 표시하는 문법입니다 ② 같은 계층에 속한 항목은 들여쓰기 칸 수가 정확히 같아야 하며, 하나라도 어긋나면 다른 계층으로 해석되거나 구조 자체가 깨집니다 ③ 화면에는 정렬돼 보여도 실제 스페이스 개수나 탭 혼용 여부는 파서에 넣어봐야 정확히 알 수 있습니다
CI 배포가 실패하는 이유 — 왜 이런 일이 생기나
GitHub Actions, GitLab CI, Kubernetes 매니페스트, docker-compose 등 대부분의 CI/CD 설정 파일은 YAML로 작성됩니다. YAML은 JSON처럼 중괄호나 대괄호로 하위 항목의 시작과 끝을 표시하지 않고, 줄의 들여쓰기 칸 수만으로 계층을 표시합니다.
같은 들여쓰기 칸 수를 가진 줄들은 같은 계층에 속하고, 더 깊이 들여쓴 줄은 바로 위 줄의 하위 항목이 됩니다. 이 규칙 때문에 스페이스 개수 자체가 문법의 일부가 되고, 칸 수가 하나라도 다르면 완전히 다른 구조로 해석됩니다.
문제는 이 차이가 눈에 잘 안 보인다는 점입니다. 에디터 화면에서는 스페이스 몇 칸이든 비슷하게 정렬돼 보이고, 다른 문서나 다른 사람의 코드에서 복사해 붙여넣은 줄은 원본의 들여쓰기 칸 수를 그대로 가져오면서 주변 줄과 어긋나기 쉽습니다.
예를 들어 여러 단계로 이루어진 steps 목록 중 하나만 스페이스 한 칸이 덜 들어가면, 그 항목이 엉뚱한 계층으로 옮겨지거나 파서가 구조 자체를 해석하지 못해 오류를 냅니다. CI 로그에는 짧은 실패 메시지만 남는 경우가 많아, 몇 번째 줄이 원인인지는 로그만으로 알기 어렵습니다.
확인하는 방법 — 어느 줄이 틀렸는지 찾기
에디터의 '공백 표시(invisible characters)' 기능을 켜면 스페이스와 탭을 서로 다른 기호로 보여줘서, 화면만 봐서는 구분이 안 되던 문자를 구별할 수 있습니다. '들여쓰기 가이드라인' 표시도 같은 계층의 줄들이 세로선으로 정렬되는지 한눈에 비교하는 데 도움이 됩니다.
이렇게 봐도 못 찾겠다면 파일을 처음 줄부터 하나씩 세어보는 방법이 있습니다. 부모 줄을 기준으로 자식 줄이 몇 칸 들여써졌는지 손으로 맞춰보면 어긋난 지점을 찾을 수 있지만, 파일이 길어질수록 시간이 오래 걸리고 세는 도중 실수하기도 쉽습니다.
저희 도구로 확인하기. YAML을 그대로 붙여넣거나 파일을 불러오면 자체 파서가 구조를 다시 해석해서, 들여쓰기가 어긋난 줄의 번호를 바로 알려줍니다.
무료 · 가입 불필요 · 브라우저에서 바로 YAML 오류 줄 번호 확인
자주 막히는 지점
| 상황 | 원인 |
|---|---|
| 에디터에서는 정렬돼 보이는데 오류가 남 | 탭과 스페이스가 섞여 있어 화면엔 같아 보여도 파서는 다른 들여쓰기로 처리합니다 |
| 다른 문서에서 복사한 YAML 조각을 붙였더니 오류 | 원본의 들여쓰기 칸 수가 현재 파일과 달라 앞뒤 줄과 계층이 어긋납니다 |
| 목록(-으로 시작하는 항목) 중 하나만 오류 | 형제 항목끼리 들여쓰기 칸 수가 한 칸이라도 다르면 그 항목만 다른 계층으로 분리됩니다 |
| CI 로그에는 오류 줄 번호가 안 나옴 | 로그는 파싱 실패 사실만 알려줄 뿐, 원인이 된 줄은 파일을 직접 검증해야 찾을 수 있습니다 |
표에 정리된 상황은 모두 '들여쓰기 칸 수가 계층을 결정한다'는 같은 규칙에서 나옵니다. 파일을 검증 도구에 넣어보면 사람이 놓치기 쉬운 이 차이를 줄 번호로 바로 확인할 수 있습니다.
정리
CI/CD 설정 파일은 대부분 YAML로 작성되고, YAML은 중괄호 대신 들여쓰기 칸 수로 계층을 표시합니다. 같은 계층의 항목은 칸 수가 정확히 같아야 하며, 한 칸만 어긋나도 다른 계층으로 해석되거나 파싱 자체가 실패합니다.
에디터의 공백 표시 기능으로 눈으로 확인하거나 칸 수를 직접 세어볼 수도 있지만, 파일이 길어질수록 검증 도구에 넣어 줄 번호로 바로 확인하는 편이 빠르고 정확합니다.
무료 · 가입 불필요 · 브라우저에서 바로 YAML 오류 줄 번호 확인
자주 묻는 질문
CI 로그에는 오류 줄 번호가 안 나오는데, 어떻게 찾나요?
CI 도구 자체 로그는 대부분 '파싱에 실패했다'는 사실만 알려주고 정확한 줄 번호까지는 알려주지 않는 경우가 많습니다. 설정 파일을 그대로 별도의 YAML 검증기에 붙여넣으면, 파서가 어느 줄부터 계층 해석이 어긋났는지 줄 번호로 알려줍니다.
들여쓰기는 스페이스 2칸과 4칸 중 뭐가 맞나요?
YAML 명세 자체는 칸 수를 강제하지 않습니다. 다만 한 파일 안에서는 같은 계층끼리 반드시 같은 칸 수를 써야 하므로, 프로젝트 전체에서 2칸이든 4칸이든 하나로 통일해서 쓰는 것이 중요합니다. GitHub Actions·GitLab CI 예제 문서는 대체로 2칸을 사용합니다.
탭과 스페이스를 섞어 써도 되나요?
안 됩니다. YAML 명세는 들여쓰기에 탭 문자를 허용하지 않습니다. 에디터마다 탭이 화면에 몇 칸으로 보이는지 다르기 때문에, 탭 하나가 스페이스 몇 개와 같은 들여쓰기인지 파서가 일관되게 판단할 수 없기 때문입니다.