• 구문 확인
  • 파이프라인 편집기에서 .gitlab-ci.yml 편집
  • 로컬에서 .gitlab-ci.yml 편집
  • CI Lint 도구로 구문 확인
• 변수 확인
• 작업 구성 문제
  • 예상치 못한 동작이 발생할 때
  • .gitlab-ci.yml 파일에 바이트 순서 표시 (BOM)가 포함되어 예상치 못한 동작
  • changes 키워드를 사용하여 작업이 예기치 않게 실행됨
  • 두 파이프라인이 동시에 실행됨
  • 파이프라인이 실행되지 않거나 잘못된 유형의 파이프라인이 실행됨
  • 많은 작업을 포함하는 파이프라인이 시작되지 못함
• 파이프라인 경고
  • 단일 작업으로 여러 파이프라인을 실행하도록 허용할 수 있음 경고
• 문제 해결
  • Merge하기 전에 반드시 CI/CD 파이프라인이 실행되고 성공해야 함 메시지
  • Checking ability to merge automatically 메시지
  • Checking pipeline status 메시지
  • Project <group/project> not found or access denied 메시지
  • The parsed YAML is too big 메시지
  • .gitlab-ci.yml 파일을 편집할 때 500 오류
  • Failed to pull image 메시지

CI/CD 파이프라인 디버깅

GitLab은 CI/CD 구성을 디버깅하기 쉽게 도와주는 여러 도구를 제공합니다.

파이프라인 문제를 해결할 수 없는 경우 다음에서 도움을 받을 수 있습니다:

• GitLab 커뮤니티 포럼
• GitLab 지원팀

구문 확인

문제의 초기 원인은 잘못된 구문일 수 있습니다. 만약 구문 또는 형식 문제가 발견되면 파이프라인에 yaml invalid 뱃지가 표시되고 실행이 시작되지 않습니다.

파이프라인 편집기에서 .gitlab-ci.yml 편집

파이프라인 편집기는 권장되는 편집 환경입니다 (단일 파일 편집기 또는 Web IDE보다). 다음을 포함합니다:

• 허용된 키워드만 사용되도록 하는 코드 완성 제안.
• 자동 구문 강조 표시 및 유효성 검사.
• CI/CD 구성 시각화, .gitlab-ci.yml 파일의 그래픽 표현.

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

파이프라인 구성을 로컬에서 편집하려면 편집기에서 GitLab CI/CD 스키마를 사용하여 기본 구문 문제를 확인할 수 있습니다. Schemastore 지원 편집기를 사용할 수 있습니다.

스키마를 직접 연결해야 하는 경우 다음 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 도구를 사용하여 전체 파이프라인 생성을 시뮬레이션할 수도 있습니다. 이는 구성 구문의 심층 검증을 수행합니다.

변수 확인

CI/CD의 문제 해결에 있어서 핵심적인 부분은 파이프라인에 존재하는 변수와 그 값들을 확인하는 것입니다. 많은 파이프라인 구성이 변수에 의존하며, 변수를 확인하는 것은 문제의 원인을 빠르게 찾는 데 도움이 됩니다.

각 문제가 있는 작업에서 전체 변수 목록을 내보내기하세요. 기대하는 변수가 있는지, 값이 기대한 대로인지 확인하세요.

작업 구성 문제

rules 또는 only/except 구성의 동작을 분석하여 많은 공통 파이프라인 문제를 해결할 수 있습니다. 이 두 구성을 동일한 파이프라인에서 사용해서는 안 되며, 다르게 동작합니다. 파이프라인이 이러한 혼합된 동작을 수행하는 것을 예측하기 어렵습니다. 작업을 제어하기 위해 rules를 선택하는 것이 좋습니다. only 및 except는 더 이상 개발되지 않고 있습니다.

만약 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 절은 원하는 방식으로 동작하는 규칙을 작성하는 데 매우 도움이 될 수 있습니다.

.gitlab-ci.yml 파일에 바이트 순서 표시 (BOM)가 포함되어 예상치 못한 동작

.gitlab-ci.yml 파일이나 다른 포함된 구성 파일에 UTF-8 바이트 순서 표시 (BOM)이 포함되어 있으면 잘못된 파이프라인 동작을 일으킬 수 있습니다. 바이트 순서 표시는 파일의 구문 분석에 영향을 주어 일부 구성이 무시될 수 있으며, 작업이 누락될 수도 있고 변수가 잘못된 값으로 대치될 수 있습니다. 일부 텍스트 편집기는 BOM 문자를 삽입할 수 있습니다.

파이프라인이 혼란스러운 동작을 하는 경우, 이를 표시할 수 있는 툴을 사용하여 BOM 문자의 존재 여부를 확인할 수 있습니다. 파이프라인 편집기에서는 문자를 표시할 수 없으므로 외부 도구를 사용해야 합니다. 자세한 내용은 이슈 35402를 참조하세요.

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 도구로 구성 유효성을 검사했을 때.
• 수동으로 파이프라인 실행했을 때.

단일 작업으로 여러 파이프라인을 실행하도록 허용할 수 있음 경고

when 절을 사용하여 rules를 사용할 때 if 절이 없는 경우 여러 파이프라인이 실행될 수 있습니다. 일반적으로 이는 브랜치에 커밋을 푸시하는 경우에 발생합니다.

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

문제 해결

특정 영역에 대한 도움이 필요한 경우 다음을 참조하세요:

• 캐싱.
• CI/CD 작업 토큰.
• 컨테이너 레지스트리.
• 도커.
• 하향 파이프라인.
• 환경.
• GitLab Runner.
• ID 토큰.
• 작업.
• 작업 제어.
• 작업 아티팩트.
• 병합 요청 파이프라인, 병합된 결과 파이프라인, 그리고 병합 기차.
• 파이프라인 편집기.
• 변수.
• YAML includes 키워드.
• YAML script 키워드.

그 외에도 알려진 상태 메시지 및 오류 메시지에 대한 다음 문제 해결 섹션을 검토하세요.

Merge하기 전에 반드시 CI/CD 파이프라인이 실행되고 성공해야 함 메시지

프로젝트에서 파이프라인이 성공해야 함 설정이 활성화되어 있고 파이프라인이 아직 성공적으로 실행되지 않은 경우 표시됩니다. 이는 파이프라인이 아직 생성되지 않았거나 외부 CI 서비스를 기다리는 경우에도 해당됩니다.

프로젝트에서 파이프라인을 사용하지 않는 경우에는 파이프라인이 성공해야 함을 비활성화하면 병합 요청을 수락할 수 있습니다.

Checking ability to merge automatically 메시지

만약 몇 분 후에도 사라지지 않는 Checking ability to merge automatically 메시지로 병합 요청이 막혀 있다면, 다음 중 하나를 시도해 볼 수 있습니다:

• 병합 요청 페이지를 새로고침합니다.
• 병합 요청을 닫고 다시 엽니다.
• /rebase 빠른 조치를 사용하여 병합 요청을 재베이스합니다.
• 이미 병합을 준비했다고 확인했다면 /merge 빠른 조치로 병합할 수 있습니다.

이 문제는 GitLab 15.5에서 해결되었습니다.

Checking pipeline status 메시지

이 메시지는 최신 커밋과 연관된 파이프라인이 아직 없는 경우에 표시됩니다. 이는 다음과 같은 이유일 수 있습니다:

• GitLab이 아직 파이프라인 생성을 완료하지 못했습니다.
• 외부 CI 서비스를 사용하고 있고 GitLab이 해당 서비스로부터 응답을 받지 못했습니다.
• 프로젝트에서 CI/CD 파이프라인을 사용하고 있지 않습니다.
• 프로젝트에서 CI/CD 파이프라인을 사용하고 있지만 구성으로 인해 병합 요청의 소스 브랜치에서 파이프라인을 실행하지 못했습니다.
• 최신 파이프라인이 삭제되었습니다(이는 알려진 문제입니다).
• 병합 요청의 소스 브랜치가 비공개 포크에 있는 경우입니다.

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

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

이 메시지는 include로 추가된 구성이 해당 프로젝트를 찾을 수 없거나 접근이 거부된 경우에 표시됩니다.

이를 해결하기 위해 다음을 확인합니다:

• 프로젝트 경로가 저장소의 어떤 폴더도 포함하지 않는 my-group/my-project 형식인지 확인합니다.
• 파이프라인을 실행할 사용자가 포함된 파일을 포함하는 프로젝트의 구성원인지 확인합니다. 또한 해당 사용자는 동일한 프로젝트에서 CI/CD 작업을 실행할 권한을 갖고 있어야 합니다.

The parsed YAML is too big 메시지

이 메시지는 YAML 구성이 너무 크거나 너무 깊게 중첩된 경우에 표시됩니다. 수많은 포함 및 수천 줄의 YAML 파일은 이러한 메모리 제한에 부딪힐 가능성이 높습니다. 예를 들어 200kb 크기의 YAML 파일은 기본 메모리 제한에 부딪힐 가능성이 높습니다.

구성 크기를 줄이려면 다음을 수행할 수 있습니다:

• 파이프라인 편집기의 전체 구성 탭에서 확장된 CI/CD 구성의 길이를 확인합니다. 제거하거나 단순화할 수 있는 중복된 구성을 찾습니다.
• 프로젝트 내에서 긴 또는 반복되는 script 섹션을 독립적인 스크립트로 이동시킵니다.
• 상위 및 하위 파이프라인을 사용하여 일부 작업을 독립적인 하위 파이프라인의 작업으로 이동합니다.

자체 관리 인스턴스에서는 최대 크기 및 깊이 제한을 늘릴 수 있습니다.

.gitlab-ci.yml 파일을 편집할 때 500 오류

포함된 구성 파일의 루프가 .gitlab-ci.yml 파일을 편집할 때 500 오류를 발생시킬 수 있습니다.

포함된 구성 파일이 서로 상호 참조하는 루프를 만들지 않도록 확인합니다.

Failed to pull image 메시지

• Allow access to this project with a CI_JOB_TOKEN 설정은 GitLab 16.3에서 Limit access to this project로 이름이 바뀌었습니다.

CI/CD 작업 중 Runner가 컨테이너 이미지를 가져오려고 시도할 때 Failed to pull image 메시지가 발생할 수 있습니다.

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

만약 작업 토큰 설정이 다른 프로젝트의 컨테이너 레지스트리 접근을 막는다면 Runner는 오류 메시지를 반환합니다.

예를 들어:

• 경고: "always" 정책으로 이미지를 가져오지 못했습니다: Daemon으로부터의 오류 응답: registry.example.com/path/to/project에 대한 풀 액세스 권한이 거부되었습니다, 저장소가 존재하지 않거나 'docker login'을 요구할 수 있음: 요청된 리소스 액세스가 거부됨
  

• 경고: ""으로 이미지를 가져오지 못했습니다: 이미지 가져오기 실패: rpc 오류: code = Unknown desc = "registry.example.com/path/to/project/image:v1.2.3" 이미지를 가져오고 풀었지 않습니다: "registry.example.com/path/to/project/image:v1.2.3"를 가져오기에 실패했습니다: 참조를 해결하지 못했고 언팩하기에 실패했습니다 "registry.example.com/path/to/project/image:v1.2.3": 풀 액세스 거부, 저장소가 존재하지 않거나 인증이 필요할 수 있음: 서버 메시지: 부족한_범위: 인가에 실패함
  

이러한 오류는 다음 조건이 모두 충족되면 발생할 수 있습니다:

• 개인 프로젝트에서 이 프로젝트의 액세스 제한 옵션이 활성화된 경우
• 이미지를 가져오려는 작업이 목록에 없는 프로젝트에서 실행 중인 경우

이 문제를 해결하려면 컨테이너 레지스트리에서 이미지를 가져오는 CI/CD 작업을 실행하는 모든 프로젝트를 대상 프로젝트의 작업 토큰 허용 목록에 추가합니다.

또한 다른 프로젝트의 이미지에 액세스하려면 프로젝트 액세스 토큰 대신에 더 넓은 범위의 다른 토큰 유형을 사용해야 합니다.