CI/CD 파이프라인 디버깅

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

GitLab은 CI/CD 구성을 디버깅하는 데 도움이 되는 여러 도구를 제공합니다.

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

구문 확인

문제의 초기 원인은 잘못된 구문일 수 있습니다. 파이프라인에 yaml invalid 배지가 표시되고 구문이나 서식에 문제가 있으면 실행이 시작되지 않습니다.

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

pipeline editor는 다음과 같은 기능이 포함된 권장 편집 환경입니다. - 수락된 키워드만 사용하도록 보장해주는 코드 완성 제안. - 자동 구문 강조 표시 및 유효성 검사. - 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 도구를 사용하여 전체 파이프라인 생성을 시뮬레이트할 수도 있습니다. 이는 구성 구문의 심층적인 확인을 수행합니다.

변수 확인

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로 평가되기 때문입니다. 예를 들어 예약된 파이프라인이나 태그용 파이프라인을 포함하여 특정 파이프라인 유형에서는 항상 true입니다.

changes 키워드는 only/except 또는 rules에서 if 섹션과 함께 사용됩니다. changes를 브랜치 파이프라인이나 Merge Request 파이프라인에만 추가되도록 하는 것이 권장됩니다.

동일한 시간에 두 개의 파이프라인이 실행됨

특정 브랜치에 커밋을 푸시할 때 두 개의 파이프라인이 실행될 수 있습니다. 일반적으로 한 파이프라인은 Merge Request 파이프라인이고, 다른 하나는 브랜치 파이프라인입니다.

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

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

파이프라인이 실행되기 전에 GitLab은 구성에서 모든 작업을 평가하고 모든 사용 가능한 파이프라인 유형에 추가하려고 시도합니다. 평가가 끝나면 작업이 파이프라인에 추가되지 않으면 파이프라인이 실행되지 않습니다.

파이프라인이 실행되지 않은 경우 모든 작업에는 파이프라인에 추가되는 것을 막는 rules 또는 only/except가 있을 수 있습니다.

잘못된 파이프라인 유형이 실행된 경우 rules 또는 only/except 구성을 확인하여 작업이 올바른 파이프라인 유형에 추가되는지 확인해야 합니다. 예를 들어, Merge Request 파이프라인이 실행되지 않은 경우 작업은 대신 브랜치 파이프라인에 추가된 경우가 있을 수 있습니다.

또한 여러분의 workflow: rules 구성이 파이프라인을 차단했거나 잘못된 파이프라인 유형을 허용했을 수도 있습니다.

많은 작업을 포함한 파이프라인이 시작되지 못함

인스턴스가 정의한 CI/CD 제한보다 많은 작업을 포함하는 파이프라인은 시작되지 않습니다.

단일 파이프라인에 있는 작업 수를 줄이려면 .gitlab-ci.yml 구성을 더 독립적인 상위-하위 파이프라인으로 분할할 수 있습니다.

파이프라인 경고

파이프라인 구성 경고는 다음 경우에 표시됩니다:

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

when 절과 함께 if 절이 없는 rules를 사용하면 단일 작업에 대해 여러 파이프라인이 실행될 수 있습니다. 이는 일반적으로 연결된 Merge Request이 있는 브랜치에 커밋을 푸시할 때 발생합니다.

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

문제 해결

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

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

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

이 메시지는 프로젝트에서 파이프라인이 성공해야 함 설정이 활성화되어 있고 파이프라인이 아직 성공적으로 실행되지 않았을 때 또는 외부 CI 서비스를 기다리고 있을 때 표시됩니다.

프로젝트에서 파이프라인을 사용하지 않는 경우 파이프라인이 성공해야 함 설정을 비활성화하여 Merge Request을 수락할 수 있습니다.

자동으로 Merge할 수 있는 능력을 확인하는 중 메시지

만일 Merge Request이 자동으로 Merge할 수 있는 능력을 확인하는 중 메시지로 멈춰있는 경우, 몇 분 후에도 사라지지 않는다면 다음 중 하나를 시도해 볼 수 있습니다:

  • Merge Request 페이지를 새로고침합니다.
  • Merge Request을 닫고 다시 엽니다.
  • /rebase 빠른 작업을 사용하여 Merge Request을 리베이스합니다.
  • 이미 Merge Request이 Merge할 준비가 되었다면 /merge 빠른 작업으로 Merge할 수 있습니다.

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

파이프라인 상태 확인 중 메시지

이 메시지는 최신 커밋과 연계된 Merge Request이 아직 파이프라인과 연계되지 않았을 때 나타납니다. 이는 다음과 같은 이유로 발생할 수 있습니다:

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

파이프라인이 생성되면 이 메시지가 파이프라인 상태로 업데이트됩니다.

프로젝트 <group/project>를 찾을 수 없거나 액세스할 수 없음 메시지

이 메시지는 다음과 같은 경우에 표시됩니다: include로 구성을 추가하고:

  • 구성이 찾을 수 없는 프로젝트를 참조하는 경우
  • 파이프라인을 실행하는 사용자가 포함된 파일을 포함하는 프로젝트에 액세스할 수 없는 경우

이 문제를 해결하려면 다음을 확인하세요:

  • 프로젝트의 경로가 my-group/my-project 형식이며 리포지터리의 어떤 폴더도 포함되어 있지 않은지 확인하세요.
  • 파이프라인을 실행하는 사용자가 포함된 파일을 포함하는 프로젝트의 구성원임을 확인하세요. 사용자는 또한 같은 프로젝트에서 CI/CD 작업을 실행할 권한을 가져야 합니다.

The parsed YAML is too big 메시지

이 메시지는 YAML 구성이 너무 크거나 너무 깊게 중첩되어 있을 때 표시됩니다. 수천 줄의 포함 파일과 수많은 라인을 가진 YAML 파일은 이러한 메모리 제한에 걸릴 가능성이 높습니다. 예를 들어, 200KB의 YAML 파일은 기본 메모리 제한에 걸릴 가능성이 높습니다.

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

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

Self-managed 인스턴스에서는 .gitlab-ci.yml 파일의 최대 크기와 깊이 제한을 늘릴 수 있습니다.

.gitlab-ci.yml 파일 편집 시 500 에러

포함된 구성 파일 루프로 인해 .gitlab-ci.yml 파일을 웹 편집기로 편집하는 중 500 에러가 발생할 수 있습니다.

포함된 구성 파일이 서로를 참조하는 루프를 생성하지 않도록 확인하세요.

Failed to pull image 메시지

CI/CD 작업에서 컨테이너 이미지를 가져오려고 할 때 실행자가 Failed to pull image 메시지를 반환할 수 있습니다.

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

작업 토큰 설정이 다른 프로젝트의 컨테이너 레지스트리에 액세스하는 것을 방지하는 경우 실행자는 오류 메시지를 반환합니다.

예를 들어: 

  • 경고: 정책 "always"로 이미지를 가져오지 못했습니다: pull 액세스가 거부되었습니다. 요청한 리소스에 대한 액세스가 거부되었거나 레지스트리가 존재하지 않거나 '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": pull 액세스 거부, 레지스트리가 존재하지 않거나 권한 부여가 필요할 수 있습니다: 서버 메시지: 충분한 범위 없음: 인증에 실패했습니다

이러한 오류는 다음이 모두 참일 때 발생할 수 있습니다:

  • 이 프로젝트에 대한 제한된 액세스 옵션이 사설 프로젝트에서 활성화되어 있는 경우
  • 이미지를 가져오려는 작업이 사설 프로젝트의 허용 디렉터리에 나열되어 있지 않은 프로젝트에서 실행 중인 경우

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

또한 다른 프로젝트의 이미지에 액세스하려면 프로젝트 액세스 토큰을 사용하는 경우에도 이러한 오류가 발생할 수 있습니다. 프로젝트 액세스 토큰은 한 프로젝트에 대해 범위가 지정되어 있기 때문에 다른 프로젝트의 이미지에 액세스할 수 없습니다. 더 넓은 범위의 다른 토큰 유형을 사용해야 합니다.