CI/CD 파이프라인 디버깅

파이프라인이 예상과 다르게 움직일 때, 어디부터 봐야 할지 막막할 때가 많아요. GitLab은 CI/CD 구성을 더 쉽게 디버깅할 수 있게 도와주는 여러 도구와 기법을 제공합니다. 이 문서는 구문 검증부터 잡 실행, 에러 메시지 해석까지 디버깅의 전 과정을 단계별로 짚어줘요.

출처: 문서

본문

GitLab은 CI/CD 구성을 더 쉽게 디버깅할 수 있게 해주는 여러 도구를 제공합니다.

파이프라인 문제를 해결하지 못하면 다음에서 도움을 받을 수 있어요.

GitLab 커뮤니티 포럼
GitLab Support

특정 CI/CD 기능에 문제가 있다면 해당 기능의 문제 해결 섹션을 참고하세요.

디버깅 기법

구문 검증

문제의 초기 원인은 잘못된 구문인 경우가 많아요. 구문이나 서식 문제가 발견되면 파이프라인은 yaml invalid 배지를 표시하고 실행을 시작하지 않습니다.

파이프라인 에디터로 `.gitlab-ci.yml` 편집

파이프라인 에디터는(단일 파일 에디터나 Web IDE보다) 권장되는 편집 경험이에요. 여기에는 다음이 포함됩니다.

허용된 키워드만 쓰게 해주는 코드 완성 제안.
자동 구문 하이라이팅과 검증.
CI/CD 구성 시각화, .gitlab-ci.yml 파일의 그래픽 표현.

`.gitlab-ci.yml`을 로컬에서 편집

파이프라인 구성을 로컬에서 편집하고 싶다면 편집기에서 GitLab CI/CD 스키마를 사용해 기본 구문 문제를 검증할 수 있어요. Schemastore 지원 편집기는 기본적으로 GitLab CI/CD 스키마를 사용합니다.

스키마를 직접 연결해야 한다면 다음 URL을 사용하세요.

https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/editor/schema/ci.json

CI/CD 스키마가 다루는 커스텀 태그 전체 목록을 보려면 스키마의 최신 버전을 확인하세요.

CI Lint 도구로 구문 검증

CI Lint 도구로 CI/CD 구성 스니펫의 구문이 올바른지 검증할 수 있어요. 전체 .gitlab-ci.yml 파일이나 개별 잡 구성을 붙여 넣어 기본 구문을 확인합니다.

프로젝트에 .gitlab-ci.yml 파일이 있으면 CI Lint 도구로 전체 파이프라인 생성을 시뮬레이션할 수도 있습니다. 이것은 구성 구문을 더 깊게 검증합니다.

파이프라인 이름 사용하기

workflow:name으로 모든 파이프라인 유형에 이름을 주면 파이프라인 목록에서 식별하기 쉬워져요. 예를 들어:

variables:
  PIPELINE_NAME: "Default pipeline name"

workflow:
  name: '$PIPELINE_NAME'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PIPELINE_NAME: "Merge request pipeline"
    - if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPELINE_SCHEDULE_TYPE == "hourly_deploy"'
      variables:
        PIPELINE_NAME: "Hourly deployment pipeline"
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      variables:
        PIPELINE_NAME: "Other scheduled pipeline"
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      variables:
        PIPELINE_NAME: "Default branch pipeline"
    - if: '$CI_COMMIT_BRANCH =~ /^\d{1,2}\.\d{1,2}-stable$/'
      variables:
        PIPELINE_NAME: "Stable branch pipeline"

CI/CD 변수

변수 검증

CI/CD 문제 해결의 핵심은 파이프라인에 어떤 변수가 있는지, 그 값이 무엇인지 확인하는 것이에요. 파이프라인 구성의 많은 부분이 변수에 의존하므로, 변수를 검증하는 것이 문제의 원인을 찾는 가장 빠른 방법 중 하나입니다.

각 문제 잡에서 사용 가능한 변수 전체 목록을 내보내 보세요. 기대하는 변수가 있는지, 값이 기대와 같은지 확인합니다.

변수로 CLI 명령에 플래그 추가하기

표준 파이프라인 실행에서는 사용되지 않지만 필요시 디버깅에 쓸 수 있는 CI/CD 변수를 정의할 수 있어요. 변수를 추가하면 파이프라인이나 개별 잡을 수동 실행할 때 값을 설정해 명령 동작을 바꿀 수 있습니다. 예를 들어:

my-flaky-job:
  variables:
    DEBUG_VARS: ""
  script:
    - my-test-command $DEBUG_VARS /test-dirs

이 예시에서 DEBUG_VARS는 표준 파이프라인에서 기본적으로 비어 있어요. 잡 동작을 디버깅해야 한다면 파이프라인을 수동으로 실행하고 DEBUG_VARS를 --verbose로 설정해 추가 출력을 얻을 수 있습니다.

의존성

의존성 관련 문제는 파이프라인에서 예상치 못한 문제를 일으키는 또 다른 흔한 원인입니다.

의존성 버전 검증

잡에서 올바른 버전의 의존성이 사용되고 있는지 검증하려면 메인 스크립트 명령을 실행하기 전에 버전을 출력해 볼 수 있어요. 예를 들어:

job:
  before_script:
    - node --version
    - yarn --version
  script:
    - my-javascript-tests.sh

버전 고정(pin)

의존성이나 이미지의 최신 버전을 항상 사용하고 싶을 수 있지만, 업데이트가 예상치 못한 breaking change를 가져올 수 있어요. 핵심 의존성과 이미지를 고정(pin)해서 갑작스러운 변경을 피하는 걸 고려해 보세요. 예를 들어:

variables:
  ALPINE_VERSION: '3.18.6'

job1:
  image: alpine:$ALPINE_VERSION  # This will never change unexpectedly
  script:
    - my-test-script.sh

job2:
  image: alpine:latest  # This might suddenly change
  script:
    - my-test-script.sh

여전히 의존성과 이미지 업데이트를 주기적으로 확인해야 해요. 중요한 보안 업데이트가 있을 수 있으니까요. 업데이트된 이미지나 의존성이 여전히 파이프라인과 함께 동작하는지 검증하는 프로세스의 일부로 버전을 수동으로 업데이트하면 됩니다.

잡 출력 검증

출력을 상세하게

--silent로 잡 로그의 출력량을 줄일 수 있어요. 하지만 이러면 잡에서 무엇이 잘못됐는지 파악하기 어려울 수 있습니다. 가능하면 --verbose를 사용하세요. 명령이 무엇을 하는지 더 자세히 보여줍니다.

job1:
  script:
    - my-test-tool --silent         # If this fails, it might be impossible to identify the issue.
    - my-other-test-tool --verbose  # This command will likely be easier to debug.

출력과 보고서를 아티팩트로 저장

일부 도구는 잡이 실행되는 동안에만 필요한 파일을 만들 수 있지만, 이 파일들의 내용은 디버깅에 쓸 수 있어요. artifacts로 나중에 분석할 수 있게 저장할 수 있습니다.

job1:
  script:
    - my-tool --json-output my-output.json
  artifacts:
    paths:
      - my-output.json

artifacts:reports로 구성된 보고서는 기본적으로 다운로드할 수 없지만, 디버깅에 도움이 되는 정보를 담고 있을 수 있어요. 이 보고서들을 검사할 수 있도록 같은 기법을 사용하세요.

job1:
  script:
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml
    paths:
      - rspec.xmp

파이프라인에 접근할 수 있는 사용자는 누구나 볼 수 있으므로, 아티팩트에 토큰, 비밀번호, 기타 민감한 정보를 저장하지 마세요.

잡 명령을 로컬에서 실행

Rancher Desktop 같은 도구를 사용해 잡의 컨테이너 이미지를 로컬 머신에서 실행할 수 있어요. 그런 다음 컨테이너 안에서 잡의 script 명령을 실행해 동작을 검증합니다.

근본 원인 분석으로 실패한 잡 문제 해결

GitLab Duo Chat에서 GitLab Duo 근본 원인 분석(Root Cause Analysis)을 사용해 실패한 CI/CD 잡을 문제 해결할 수 있어요.

잡 구성 문제

흔한 파이프라인 문제 중 상당수는 rules 또는 only/except 구성의 동작을 분석해서 고칠 수 있어요. 이 구성은 잡이 언제 파이프라인에 추가되는지 제어하는 데 사용됩니다. 이 두 구성을 같은 파이프라인에서 함께 쓰면 안 돼요. 동작이 서로 다르기 때문입니다. 이런 혼합 동작으로 파이프라인이 어떻게 실행될지 예측하기 어려워요. only와 except는 더 이상 활발히 개발되지 않으므로 잡 제어에는 rules가 선호되는 선택입니다.

rules 또는 only/except 구성이 CI_PIPELINE_SOURCE, CI_MERGE_REQUEST_ID 같은 사전 정의 변수를 사용한다면, 첫 번째 문제 해결 단계로 그것들을 검증하세요.

잡이나 파이프라인이 예상대로 실행되지 않을 때

rules 또는 only/except 키워드는 잡이 파이프라인에 추가될지 여부를 결정합니다. 파이프라인은 실행되는데 잡이 추가되지 않는다면, 보통 rules 또는 only/except 구성 문제 때문이에요.

파이프라인이 오류 메시지 없이 전혀 실행되지 않는 것처럼 보인다면, 이것도 rules 또는 only/except 구성, 또는 workflow: rules 키워드 때문일 수 있어요.

only/except에서 rules 키워드로 전환하고 있다면 rules 구성 세부 사항을 신중히 확인해야 합니다. only/except와 rules의 동작은 다르며, 둘 사이를 옮길 때 예상치 못한 동작을 일으킬 수 있어요.

rules의 일반적인 if 절은 기대한 대로 동작하는 rules를 작성하는 예시로 매우 유용합니다.

파이프라인에 .pre 또는 .post 스테이지의 잡만 있다면 실행되지 않습니다. 다른 스테이지에 잡이 최소 하나는 있어야 해요.

`.gitlab-ci.yml` 파일에 BOM(바이트 순서 표시)이 있을 때의 예상치 못한 동작

.gitlab-ci.yml 파일이나 다른 include된 구성 파일의 UTF-8 바이트 순서 표시(BOM)는 잘못된 파이프라인 동작을 일으킬 수 있어요. 바이트 순서 표시는 파일 파싱에 영향을 줍니다. 그 결과 일부 구성이 무시되고, 잡이 누락되며, 변수 값이 잘못될 수 있습니다. 일부 텍스트 편집기는 그렇게 구성되어 있으면 BOM 문자를 삽입할 수 있어요.

파이프라인에 혼란스러운 동작이 있다면, BOM 문자를 표시할 수 있는 도구로 BOM 문자의 존재를 확인해 보세요. 파이프라인 에디터는 문자를 표시할 수 없으므로 외부 도구를 사용해야 합니다. 자세한 내용은 이슈 354026을 참고하세요.

`changes` 키워드가 있는 잡이 예상치 못하게 실행될 때

잡이 예상치 못하게 파이프라인에 추가되는 흔한 이유는 changes 키워드가 특정 경우에 항상 true로 평가되기 때문이에요. 예를 들어 changes는 예약 파이프라인과 태그용 파이프라인 같은 특정 파이프라인 유형에서 항상 true입니다.

changes 키워드는 only/except 또는 rules와 함께 사용됩니다. changes는 잡이 브랜치 파이프라인이나 머지 리퀘스트 파이프라인에만 추가되도록 보장하는 rules 또는 only/except 구성의 if 섹션과 함께만 사용하는 걸 권장해요.

두 파이프라인이 동시에 실행될 때

열린 머지 리퀘스트가 연결된 브랜치에 커밋을 푸시하면 두 파이프라인이 실행될 수 있어요. 보통 하나는 머지 리퀘스트 파이프라인이고, 다른 하나는 브랜치 파이프라인입니다.

이 상황은 보통 rules 구성 때문에 발생하며, 중복 파이프라인을 방지하는 방법이 여러 가지 있습니다.

파이프라인이 실행되지 않거나 잘못된 유형의 파이프라인이 실행될 때

파이프라인이 실행되기 전에 GitLab은 구성의 모든 잡을 평가하고, 가능한 모든 파이프라인 유형에 추가하려고 합니다. 평가가 끝날 때 어떤 잡도 추가되지 않으면 파이프라인은 실행되지 않아요.

파이프라인이 실행되지 않았다면 모든 잡의 rules 또는 only/except가 파이프라인에 추가되는 것을 막았을 가능성이 큽니다.

잘못된 파이프라인 유형이 실행됐다면, 잡이 올바른 파이프라인 유형에 추가되도록 rules 또는 only/except 구성을 확인해야 합니다. 예를 들어 머지 리퀘스트 파이프라인이 실행되지 않았다면, 잡이 대신 브랜치 파이프라인에 추가됐을 수 있어요.

workflow: rules 구성이 파이프라인을 막았거나 잘못된 파이프라인 유형을 허용했을 수도 있습니다.

풀 미러링을 사용한다면 풀 미러링 파이프라인의 문제 해결 항목을 확인해 보세요.

잡이 많은 파이프라인이 시작에 실패할 때

인스턴스의 정의된 CI/CD 제한보다 더 많은 잡이 있는 파이프라인은 시작에 실패합니다.

단일 파이프라인의 잡 수를 줄이려면 .gitlab-ci.yml 구성을 더 독립적인 부모-자식 파이프라인으로 나눌 수 있어요.

파이프라인 경고

파이프라인 구성 경고는 다음 때 표시됩니다.

CI Lint 도구로 구성 검증할 때.
파이프라인을 수동으로 실행할 때.

`Job may allow multiple pipelines to run for a single action` 경고

if 절 없이 when 절로 rules를 사용하면 여러 파이프라인이 실행될 수 있어요. 보통 열린 머지 리퀘스트가 연결된 브랜치에 커밋을 푸시할 때 발생합니다.

중복 파이프라인을 방지하려면 workflow: rules을 사용하거나, 어떤 파이프라인이 실행될 수 있는지 제어하도록 rules를 다시 작성하세요.

파이프라인 오류

오류: `Identity verification is required in order to run CI jobs`

GitLab.com에서 무료 플랜으로 GitLab 호스티드 러너를 사용할 때 Identity verification is required in order to run CI jobs라는 오류 메시지가 보이면 신원 인증을 완료해야 합니다.

이 요구 사항은 무료 컴퓨팅 리소스의 남용을 방지하는 데 도움이 됩니다. 위험 점수에 따라 이메일, 전화번호 인증을 하거나 결제 수단을 추가해야 할 수 있어요. 자세한 내용은 신원 인증을 참고하세요.

검증을 완료하려면:

알림 배너에서 Verify my account를 선택하세요.
메시지가 표시되면 신원 인증 단계를 따릅니다. 전화번호를 인증하거나 결제 수단을 추가해야 할 수 있습니다.
새 커밋을 만들거나 새 파이프라인을 수동으로 트리거합니다.

대안으로 다음을 할 수 있어요.

유료 플랜으로 업그레이드.
네임스페이스에 컴퓨트 분 추가 구매.
GitLab 호스티드 러너 대신 프로젝트 또는 그룹 러너 사용.
그룹 오너에게 셀프 매니지드 러너 설정 요청.

`A CI/CD pipeline must run and be successful before merge` 메시지

이 메시지는 프로젝트에서 Pipelines must succeed 설정이 활성화되어 있는데 아직 파이프라인이 성공적으로 실행되지 않았을 때 표시됩니다. 파이프라인이 아직 생성되지 않았거나 외부 CI 서비스를 기다리는 경우에도 적용됩니다.

프로젝트에서 파이프라인을 사용하지 않는다면 머지 리퀘스트를 수락할 수 있도록 Pipelines must succeed를 비활성화하세요.

`Checking ability to merge automatically` 메시지

머지 리퀘스트가 몇 분이 지나도 사라지지 않는 Checking ability to merge automatically 메시지로 멈춰 있다면 다음 우회 방법 중 하나를 시도해 보세요.

머지 리퀘스트 페이지 새로고침.
머지 리퀘스트 닫기 & 다시 열기.
/rebase 퀵 액션으로 머지 리퀘스트 리베이스.
머지 리퀘스트가 머지 준비가 된 것을 이미 확인했다면 /merge 퀵 액션으로 머지.

`Checking pipeline status` 메시지

이 메시지는 최신 커밋에 연결된 파이프라인이 아직 없을 때 회전하는 상태 아이콘(spinner)과 함께 표시됩니다. 다음 이유 때문일 수 있어요.

GitLab이 아직 파이프라인 생성을 끝내지 못함.
외부 CI 서비스를 사용 중인데 GitLab이 아직 서비스로부터 응답을 받지 못함.
프로젝트에서 CI/CD 파이프라인을 사용하지 않음.
프로젝트에서 CI/CD 파이프라인을 사용하지만, 구성이 머지 리퀘스트의 소스 브랜치에서 파이프라인이 실행되지 않게 막음.
최신 파이프라인이 삭제됨(알려진 이슈).
머지 리퀘스트의 소스 브랜치가 프라이빗 포크에 있음.

파이프라인이 생성된 후에는 메시지가 파이프라인 상태로 업데이트됩니다.

이런 경우 중 일부에서는 Pipelines must succeed 설정이 활성화되어 있으면 아이콘이 무한히 회전하면서 메시지가 멈출 수 있어요. 자세한 내용은 이슈 334281을 참고하세요.

`Project <group/project> not found or access denied` 메시지

이 메시지는 include로 구성이 추가됐는데 다음 중 하나일 때 표시됩니다.

구성이 찾을 수 없는 프로젝트를 참조할 때.
파이프라인을 실행하는 사용자가 include된 프로젝트에 접근할 수 없을 때.

이를 해결하려면 다음을 확인하세요.

프로젝트 경로가 my-group/my-project 형식이고 저장소에 폴더를 포함하지 않는지.
파이프라인을 실행하는 사용자가 include된 파일이 있는 프로젝트의 멤버인지. 사용자에게 같은 프로젝트에서 CI/CD 잡을 실행할 권한도 있어야 합니다.

`The parsed YAML is too big` 메시지

이 메시지는 YAML 구성이 너무 크거나 너무 깊게 중첩되어 있을 때 표시됩니다. include가 많고 전체 수천 줄에 달하는 YAML 파일이 이 메모리 제한에 걸릴 가능성이 높아요. 예를 들어 200 kb인 YAML 파일은 기본 메모리 제한에 걸릴 가능성이 큽니다.

구성 크기를 줄이려면 다음을 할 수 있어요.

파이프라인 에디터의 Full configuration 탭에서 확장된 CI/CD 구성의 길이를 확인합니다. 제거하거나 단순화할 수 있는 중복 구성을 찾아보세요.
길거나 반복되는 script 섹션을 프로젝트의 독립 스크립트로 옮깁니다.
부모-자식 파이프라인을 사용해 일부 작업을 독립적인 자식 파이프라인의 잡으로 옮깁니다.

GitLab Self-Managed에서는 크기 제한을 늘릴 수 있어요.

`.gitlab-ci.yml` 파일 편집 시 `500` 오류

include된 구성 파일의 루프가 웹 에디터로 .gitlab-ci.yml 파일을 편집할 때 500 오류를 일으킬 수 있어요.

include된 구성 파일이 서로를 참조하는 루프를 만들지 않도록 하세요.

`Failed to pull image` 메시지

러너가 CI/CD 잡에서 컨테이너 이미지를 가져오려고 할 때 Failed to pull image 메시지를 반환할 수 있어요.

러너는 다른 프로젝트의 컨테이너 레지스트리에서 image 로 정의된 컨테이너 이미지를 가져올 때 CI/CD 잡 토큰으로 인증합니다.

잡 토큰 설정이 다른 프로젝트의 컨테이너 레지스트리에 대한 접근을 막으면 러너가 오류 메시지를 반환합니다.

예를 들어:

WARNING: Failed to pull image with policy "always": Error response from daemon: pull access denied for registry.example.com/path/to/project, repository does not exist or may require 'docker login': denied: requested access to the resource is denied
WARNING: Failed to pull image with policy "": image pull failed: rpc error: code = Unknown desc = failed to pull and unpack image "registry.example.com/path/to/project/image:v1.2.3": failed to resolve reference "registry.example.com/path/to/project/image:v1.2.3": pull access denied, repository does not exist or may require authorization: server *** insufficient_scope: authorization failed

이 오류는 다음 두 가지가 모두 true일 때 발생할 수 있어요.

이미지를 호스팅하는 프라이빗 프로젝트에서 Limit access to this project 옵션이 활성화됨.
이미지를 가져오려는 잡이 프라이빗 프로젝트의 허용 목록에 없는 프로젝트에서 실행됨.

이 문제를 해결하려면 컨테이너 레지스트리에서 이미지를 가져오는 CI/CD 잡이 있는 모든 프로젝트를 대상 프로젝트의 잡 토큰 허용 목록에 추가하세요.

프로젝트 접근 토큰으로 다른 프로젝트의 이미지에 접근하려고 할 때도 이 오류가 발생할 수 있어요. 프로젝트 접근 토큰은 하나의 프로젝트에만 범위가 지정되므로, 다른 프로젝트의 이미지에는 접근할 수 없습니다. 더 넓은 범위의 다른 토큰 유형을 사용해야 해요.

무작위 또는 간헐적 `Failed to pull image` 오류

CI/CD 잡에서 간헐적 Failed to pull image 오류를 경험할 수 있어요.

이 문제는 사용자마다 이미지 접근 권한이 다르고, 러너가 그 이미지를 캐시하는 방식이 결합되어 발생할 수 있습니다. 봇 사용자는 다른 프로젝트 멤버와 권한이 다른 경우가 많아 자주 영향을 받아요.

예를 들어 파이프라인 이미지가 다른 프로젝트의 컨테이너 레지스트리에 호스팅되어 있을 수 있습니다. 모든 사용자가 두 프로젝트에 접근할 수 있으면 문제가 없어요. 하지만 이미지를 호스팅하는 프로젝트에 어떤 사용자(봇 사용자 같은)가 접근할 수 없다면 Failed to pull image 오류가 발생할 수 있어요.

러너가 이미지에 접근 권한이 있는 사용자를 위해 이미지를 성공적으로 가져와 캐시하면 오류가 간헐적으로 변합니다. 이 러너는 이제 이미지를 사용할 수 있게 되어 다른 프로젝트에 접근해 이미지를 가져올 필요가 없어요. 다른 프로젝트에 접근할 수 없는 사용자를 포함해 모든 사용자가 이 이미지로 CI/CD 잡을 실행할 수 있습니다. 하지만 러너가 이미지를 한 번도 가져와 캐시한 적이 없으면, 이미지 프로젝트에 접근 권한이 없는 사용자는 Failed to pull image 오류를 받습니다.

이 문제를 해결하려면 봇 사용자를 포함해 파이프라인을 실행하는 모든 사용자가 가져오는 이미지를 호스팅하는 프로젝트에 접근할 수 있게 하세요.

파이프라인 실행 시 `Something went wrong on our end` 메시지 또는 `500` 오류

다음 파이프라인 오류를 받을 수 있어요.

머지 리퀘스트를 푸시하거나 만들 때 Something went wrong on our end 메시지.
API로 파이프라인을 트리거할 때 500 오류.

이 오류는 프로젝트를 가져온 후 내부 ID 기록이 동기화되지 않을 때 발생할 수 있어요.

이를 해결하려면 이슈 352382의 우회 방법을 참고하세요.

`config should be an array of hashes` 오류 메시지

배열에서 여러 !reference 태그를 사용할 때 다음과 비슷한 오류를 볼 수 있어요.

This GitLab CI configuration is invalid: jobs:my_job_name:parallel:matrix config should be an array of hashes.

script, rules, stages 키워드는 여러 참조 태그 사용을 지원하지만, 배열을 기대하는 다른 키워드는 지원하지 않습니다. 중첩을 사용해 이 제한을 우회하거나 YAML 앵커를 대신 사용할 수 있어요.

오류: `jobs:<job-name> config should contain either a trigger or a needs:pipeline.`

이 오류는 .gitlab-ci.yml의 잡이 needs 키워드를 사용하지만 script: 또는 trigger: 키워드를 사용하지 않을 때 발생할 수 있어요.

모든 잡은 script 또는 trigger 키워드를 사용해야 하므로, 둘 다 사용하지 않는 잡에 적절한 키워드를 추가하세요.

오류: `config contains unknown keys: <key-name>`

<keyword> config contains unknown keys: <key-name> 같은 오류를 받을 수 있어요.

이 오류 메시지는 여러 문제로 인해 발생할 수 있습니다.

키워드의 오타. 예: image(유효) 대신 imag(잘못).
키워드나 잡의 잘못된 공백 또는 들여쓰기.

예를 들어:

test-job:
  artifacts:
    path:        # This is a typo, it should be `paths`
      - test
    image: test  # This indentation is incorrect, it should be at the same level as `script`.
  script:
    - echo

더 알아보기

디버깅의 기본 순서는 구문 검증(에디터·CI Lint) → 변수 확인 → 잡 출력(verbose·아티팩트) → 로컬 재현 순서예요. 에러 메시지가 명확하지 않을 땐 rules/only/except 구성과 BOM·중복 파이프라인 같은 알려진 함정을 먼저 떠올리면 시간을 아낄 수 있어요. 다음으로는 CI Lint 도구와 파이프라인 에디터 문서를 깊이 보면 검증 도구를 충분히 활용할 수 있습니다.

CI/CD 파이프라인 디버깅