GitLab CI YAML 파일 검증을 푸시 전에 완벽하게 하는 방법

코드를 푸시하고 파이프라인이 시작되길 기다렸는데... 바로 실패. 42번째 줄에서 문법 오류. 또다시. 돌아오지 않을 15분이 날아갔습니다.

💡 팁: YAMLforge Pro로 무제한 변환을 통해 어떤 작업량도 처리하세요. 더 이상 일일 제한이 없습니다!

→ 관련 기사: Kubernetes YAML 검증으로 배포 오류 없애는 완벽 가이드

YF군이야 🤖 — 이 글, 나랑 같이 읽어보자! YAML 들여쓰기 문제로 디버깅한 횟수는 셀 수도 없어. 중요한 부분에서 끼어들 테니까 편하게 따라와!

😅 YF군: 새벽 2시 설정 파일 디버깅... 다들 한 번쯤 겪었지?

😅 YF군: 나 한번은 파이프라인 디버깅하는 데 두 시간을 썼는데, 알고 보니 스페이스 대신 탭을 썼더라고. 근데 에러 메시지는? 완전 엉뚱한 소리만. YAML은 원래 까다로워.

GitLab CI YAML 검증이란 무엇인가요?

GitLab CI는 .gitlab-ci.yml 파일을 사용해서 파이프라인을 정의합니다. 어떤 작업이 실행되고, 어떤 순서로, 어떤 조건에서 실행될지 모두 이 파일이 제어하죠. 테스트 실행부터 프로덕션 배포까지 전부요.

검증은 YAML 문법이 올바른지, 그리고 GitLab의 특정 스키마 규칙을 따르는지 확인합니다. 누락된 키, 잘못된 들여쓰기, 유효하지 않은 작업 이름, 잘못된 스테이지 정의 같은 오류를 실제 파이프라인이 망가지기 전에 잡아낼 수 있습니다.

CI 설정 파일용 맞춤법 검사기라고 생각하면 됩니다. 로직이 맞는지는 알려주지 못하지만, 콜론을 빠뜨렸거나 들여쓰기가 틀렸다면 확실히 알려줍니다.

🤔 YF군: GitLab의 YAML 파서는 생각보다 엄격해. 일반 YAML에서 되는 게 CI 설정에서는 안 될 때가 있거든. 예를 들면 include로 다른 파일 불러올 때는 앵커를 못 써. 이것도 삽질하면서 배웠지.

GitLab CI YAML 검증하는 방법

🔗 API 액세스: Pro API로 YAML 변환을 워크플로우에 통합하세요.

방법 1: GitLab 내장 CI Lint 도구

GitLab은 https://gitlab.com/[your-project]/-/ci/lint에서 전용 검증 도구를 제공합니다. 프로젝트의 CI/CD 설정에서 접근할 수 있어요.

단계:

1. GitLab 프로젝트로 이동
2. CI/CD → Editor 또는 CI/CD → Pipelines → CI Lint로 이동
3. YAML 내용 붙여넣기
4. Validate 클릭

도구가 보여주는 것:

• ✅ 줄 번호와 함께 문법 오류 표시
• ✅ 확장 프로그램된 설정 (include가 해석된 상태)
• ✅ 파이프라인 스테이지와 작업이 어떻게 보일지 미리보기

💡 YF군: CI Lint 도구는 실제로 전체 설정을 시뮬레이션해. extends, include 구문, 변수 치환까지 다 해석해줘. 복잡한 멀티 파일 구성 작업할 때 엄청 유용해.

방법 2: GitLab API 사용하기

자동화나 로컬 검증을 위해서는 GitLab API를 직접 호출할 수 있습니다:

curl --header "Content-Type: application/json" \
     --header "PRIVATE-TOKEN: your_token" \
     --data '{"content": "your-yaml-here"}' \
     "https://gitlab.com/api/v4/ci/lint"

검증 상태와 발견된 오류를 JSON으로 반환합니다.

🚀 YF군: 이거 pre-commit 훅에 넣으면 좋아. 로컬에서 검증하고 푸시하면 팀원들 파이프라인 터뜨릴 일이 없지. 다들 고마워할걸?

방법 3: YAMLforge로 빠른 문법 체크하기

GitLab 도구들이 GitLab 전용 규칙을 체크한다면, 때로는 그냥 YAML 문법 자체가 유효한지만 확인하고 싶을 때가 있죠. YAMLforge가 그럴 때 도움이 됩니다:

자동화가 필요하신가요? Pro는 완전한 API 통합을 포함합니다.

# 예시 .gitlab-ci.yml
stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Building the app"
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/

test_job:
  stage: test
  script:
    - npm test
  coverage: '/Coverage: \d+\.\d+%/'

deploy_job:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main

YAMLforge로 JSON으로 변환해서 구조적 문제를 발견할 수 있습니다:

{
  "stages": [
    "build",
    "test",
    "deploy"
  ],
  "build_job": {
    "stage": "build",
    "script": [
      "echo \"Building the app\"",
      "npm install",
      "npm run build"
    ],
    "artifacts": {
      "paths": [
        "dist/"
      ]
    }
  },
  "test_job": {
    "stage": "test",
    "script": [
      "npm test"
    ],
    "coverage": "/Coverage: \\d+\\.\\d+%/"
  },
  "deploy_job": {
    "stage": "deploy",
    "script": [
      "./deploy.sh"
    ],
    "only": [
      "main"
    ]
  }
}

🎯 YF군: YAMLforge가 YAML을 유효한 JSON으로 파싱 못 하면, GitLab도 절대 못 써. CI Lint 도구 들어가기 전에 빠른 정신건강 체크용으로 딱이야.

자주 하는 GitLab CI YAML 실수들

1. 들여쓰기 오류

YAML은 공백에 민감합니다. 들여쓰기를 섞어 쓰면 전부 망가집니다:

# ❌ 잘못됨 - 일관성 없는 들여쓰기
build_job:
  stage: build
  script:
   - echo "Hello"  # 스페이스 1개만
    - npm install  # 스페이스 4개 - 일관성 없음!

# ✅ 올바름 - 일관된 2칸 들여쓰기
build_job:
  stage: build
  script:
    - echo "Hello"
    - npm install

⚠️ YF군: 스페이스를 써, 탭 절대 금지. 대부분 에디터에서 설정 가능해. VS Code YAML 확장 프로그램 쓰면 이거 틀리면 바로 소리 질러줘. 믿고 켜두라고.

2. CI 설정에서의 노르웨이 문제

기억하세요, YAML은 특정 문자열을 불리언으로 해석합니다:

# ❌ 예상치 못한 방식으로 망가짐
variables:
  DEPLOY_TO: NO  # false가 됨!
  ENABLE_CACHE: YES  # true가 됨!
  DEBUG_MODE: OFF  # 이것도 false가 됨!

GitLab은 이걸 불리언 값으로 읽습니다. 문자열이 아니라요. 배포 스크립트가 "NO"를 문자열로 기대하는데 false를 받게 됩니다.

# ✅ 따옴표로 감싸서 문자열로 보존
variables:
  DEPLOY_TO: "NO"
  ENABLE_CACHE: "YES"
  DEBUG_MODE: "OFF"

😅 YF군: 노르웨이 문제가 또 등장. 누군가 PRODUCTION: NO를 따옴표 없이 설정해서 엉뚱한 환경에 배포한 적이 있어. 배포 스크립트가 그걸 false로 읽었고(bash에서는 truthy), 그래서... 프로덕션에 개발 빌드가 올라갔지. 재밌었어.

3. 유효하지 않은 스테이지 참조

# ❌ 존재하지 않는 스테이지를 참조하는 작업
stages:
  - build
  - test

deploy_job:
  stage: deploy  # 오류! 'deploy' 스테이지가 정의되지 않음
  script:
    - ./deploy.sh

# ✅ 모든 스테이지를 먼저 선언해야 함
stages:
  - build
  - test
  - deploy  # 이제 정의됨

deploy_job:
  stage: deploy
  script:
    - ./deploy.sh

4. 잘못된 only와 except 문법

# ❌ 잘못됨 - only는 배열을 기대함
deploy_job:
  stage: deploy
  only: main  # 작동 안 함
  script:
    - ./deploy.sh

# ✅ 올바름 - 배열 문법 사용
deploy_job:
  stage: deploy
  only:
    - main  # 적절한 배열 형식
  script:
    - ./deploy.sh

아니면 더 나은 방법으로, 최신 rules 문법을 사용하세요:

# ✅ rules를 사용한 현대적 접근
deploy_job:
  stage: deploy
  script:
    - ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

💡 YF군: GitLab이 only랑 except에서 rules로 방향을 틀고 있어. 더 강력하고 훨씬 읽기 좋거든. &&랑 ||로 조건 결합하고, 변수 체크하고, 파일 변경 감지하고, 온갖 걸 다 할 수 있어.

고급 검증 기법

gitlab-ci-lint로 pre-commit 훅 설정하기

gitlab-ci-lint CLI 도구를 설치하세요:

npm install -g gitlab-ci-lint

.git/hooks/pre-commit 스크립트를 만드세요:

#!/bin/bash

if [ -f .gitlab-ci.yml ]; then
  echo "Validating .gitlab-ci.yml..."
  gitlab-ci-lint .gitlab-ci.yml
  if [ $? -ne 0 ]; then
    echo "❌ GitLab CI validation failed. Fix errors before committing."
    exit 1
  fi
  echo "✅ GitLab CI validation passed"
fi

이제 망가진 설정을 커밋하고 싶어도 할 수 없습니다.

에디터에서 스키마 검증 설정하기

대부분의 최신 에디터가 YAML 스키마 검증을 지원합니다. VS Code에서는 Red Hat의 "YAML" 확장 프로그램을 설치하고 설정에 추가하세요:

→ 함께 읽기: YAML을 JSON으로 3초만에 변환하는 가장 쉬운 방법

{
  "yaml.schemas": {
    "https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json": ".gitlab-ci.yml"
  }
}

입력하면서 실시간 검증, 자동완성, 인라인 문서를 받을 수 있습니다.

🚀 YF군: 이거 내 인생 바꿨어. GitLab CI 키워드 자동완성? 작업 속성에 호버 문서? 좋지. 파일 저장하기도 전에 오류의 90%를 잡아내.

프라이버시와 보안 고려사항

CI 설정 검증할 때는 보안을 염두에 두세요:

• 민감한 데이터를 절대 공개 검증 도구에 붙여넣지 마세요
• 검증 전에 시크릿을 제거하세요 (플레이스홀더 값 사용)
• 개인 정보가 있는 설정은 GitLab 내장 도구를 사용하세요
• YAMLforge는 로컬에서 처리합니다 - 데이터가 브라우저를 떠나지 않습니다

🎯 YF군: 진심으로, 프로덕션 API 키를 아무 온라인 검증기에나 붙여넣지 마. 실제로 본 적 있어. 민감한 건 GitLab 자체 도구 쓰거나, 완전히 클라이언트 측에서 돌아가는 YAMLforge를 써. 시크릿은 시크릿으로 남아야지.

비교: GitLab CI Lint vs. 일반 YAML 검증기

종합 검증에는 GitLab의 CI Lint를 사용하세요. 빠른 문법 체크와 프라이버시에 민감한 설정에는 YAMLforge를 사용하세요. 둘 다 쓰는 게 최고의 워크플로우입니다.

🎉 YF군: 끝! 이제 직접 해볼 차례야. 화이팅!

자주 묻는 질문

GitLab CI YAML 파일을 어떻게 검증하나요?
GitLab의 내장 CI Lint 도구를 https://gitlab.com/[your-project]/-/ci/lint에서 사용하세요. YAML을 붙여넣고 Validate를 클릭하면 됩니다. 문법과 GitLab 전용 스키마 규칙을 모두 체크합니다.

GitLab CI YAML을 오프라인에서도 검증할 수 있나요?
네. 로컬 검증을 위해 gitlab-ci-lint npm 패키지를 설치하거나, GitLab 스키마와 함께 VS Code의 YAML 확장 프로그램 같은 에디터 플러그인을 사용해서 코딩하면서 실시간으로 검증할 수 있습니다.

YAML 검증과 GitLab CI 검증의 차이는 무엇인가요?
YAML 검증은 문법이 맞는지 확인합니다(들여쓰기, 콜론, 대시). GitLab CI 검증은 GitLab의 스키마도 따르는지 체크합니다. 유효한 작업 이름, 스테이지 참조, 올바른 rules 문법 등을 검사하죠.

유효한 YAML인데도 GitLab CI에서 실패하는 이유는 무엇인가요?
GitLab은 기본 YAML 문법을 넘어서 특정 요구사항이 있습니다. 흔한 문제: 정의되지 않은 스테이지, 유효하지 않은 작업 키워드, 잘못된 only/except 배열, 또는 include된 파일 간 앵커처럼 지원되지 않는 YAML 기능 사용.

온라인 검증기에 CI 설정을 붙여넣어도 안전한가요?
시크릿이 없는 설정이라면 괜찮습니다. 하지만 민감한 토큰, 비밀번호, API 키는 먼저 제거하세요. 더 좋은 방법은 GitLab 자체 도구나 브라우저에서만 처리하는 YAMLforge 같은 클라이언트 측 검증기를 사용하는 것입니다.

→ 더 알아보기: YAML 문법 오류, 3분 안에 해결하는 개발자 가이드

GitLab CI에서 노르웨이 문제란 무엇인가요?
YAML은 NO, YES, ON, OFF를 따옴표 없으면 불리언으로 변환합니다. CI 설정에서 이것은 환경 변수나 조건부 로직을 망가뜨릴 수 있습니다. 항상 이 값들을 따옴표로 감싸세요: DEPLOY: NO 대신 DEPLOY: "NO"로 작성해서 문자열로 보존하세요.

오늘부터 더 스마트하게 검증하세요

이제 프로처럼 GitLab CI YAML 파일을 검증하는 방법을 알았습니다:

• ✅ 종합적인 체크를 위해 GitLab의 CI Lint 도구 사용하기
• ✅ 로컬 검증으로 문법 오류 조기 발견하기
• ✅ 노르웨이 문제 같은 흔한 실수 피하기
• ✅ pre-commit 훅 설정해서 망가진 설정 방지하기
• ✅ 실시간 검증을 위해 에디터 스키마 사용하기

🎉 YF군: 다 준비됐어! 이제 바보 같은 문법 오류로 파이프라인 터뜨릴 일 없어. 그리고 YAML 문법 빠르게 체크하거나 포맷 변환할 일 있으면 YAMLforge가 있잖아. 완전 무료에 가입도 필요 없어. 자, 이제 나가서 믿음직한 파이프라인을 만들어봐!

---

무제한 변환이 필요하신가요? YAMLforge Pro 체험 - 무제한 액세스, API, 우선 지원 및 팀 기능. 월 ₩11,700, 30일 환불 보장.

관련 기사

• Kubernetes YAML 검증으로 배포 오류 없애는 완벽 가이드 - 더 읽기 → 두 시간 디버깅했는데 YAML 들여쓰기 하나 때문이었다면? Kubernetes YAML 검증 도구로 배포 전에 오류를 잡아내고 다운타임을 방지하는 실전 방법을 알려드립니다.

• YAML을 JSON으로 3초만에 변환하는 가장 쉬운 방법 - 더 읽기 → 설정 파일 마이그레이션 중인데 YAML을 JSON으로 당장 변환해야 하나요? 데이터 타입을 망가뜨리거나 Chrome 확장 프로그램 설치를 요구하지 않는 안전한 방법을 알려드립니다....

• YAML 문법 오류, 3분 안에 해결하는 개발자 가이드 - 더 읽기 → CI/CD 파이프라인이 새벽 3시에 멈췄나요? YAML 문법 오류를 빠르게 찾고 해결하는 실전 노하우를 공유합니다. 탭과 스페이스 혼용부터 노르웨이 문제까지, 흔한 실수 5가지와 ...