CI/CD 파이프라인 디버깅
Offering: GitLab.com, Self-managed, GitLab Dedicated
GitLab은 CI/CD 구성을 디버깅하는 데 도움이 되는 여러 도구를 제공합니다.
파이프라인 문제를 해결할 수 없는 경우 다음에서 도움을 받을 수 있습니다:
- GitLab 커뮤니티 포럼
- GitLab 지원
특정 CI/CD 기능에 문제가 있는 경우, 해당 기능의 관련 문제 해결 섹션을 확인하세요:
- 캐싱.
- CI/CD 작업 토큰.
- 컨테이너 레지스트리.
- 도커.
- 다운스트림 파이프라인.
- 환경.
- GitLab 러너.
- ID 토큰.
- 작업.
- 작업 아티팩트.
-
병합 요청 파이프라인,
병합 결과 파이프라인,
및 병합 열차. - 파이프라인 편집기.
- 변수.
-
YAML
includes
키워드. -
YAML
script
키워드.
디버깅 기법
구문 확인
문제의 초기 원인은 잘못된 구문일 수 있습니다. 파이프라인은 yaml invalid
배지를 표시하며, 구문 또는 형식 문제를 발견하면 실행을 시작하지 않습니다.
파이프라인 편집기로 .gitlab-ci.yml
수정
파이프라인 편집기는 추천하는 편집 경험입니다(단일 파일 편집기나 웹 IDE보다). 여기에는:
- 수락된 키워드만 사용하도록 보장하는 코드 완성 제안.
- 자동 구문 강조 및 검증.
-
.gitlab-ci.yml
파일의 그래픽 표현인 CI/CD 구성 시각화.
로컬에서 .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: "기본 파이프라인 이름"
workflow:
name: '$PIPELINE_NAME'
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
PIPELINE_NAME: "병합 요청 파이프라인"
- if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPELINE_SCHEDULE_TYPE == "hourly_deploy"'
variables:
PIPELINE_NAME: "시간별 배포 파이프라인"
- if: '$CI_PIPELINE_SOURCE == "schedule"'
variables:
PIPELINE_NAME: "기타 예약 파이프라인"
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
variables:
PIPELINE_NAME: "기본 브랜치 파이프라인"
- if: '$CI_COMMIT_BRANCH =~ /^\d{1,2}\.\d{1,2}-stable$/'
variables:
PIPELINE_NAME: "안정적인 브랜치 파이프라인"
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
버전 고정
의존성이나 이미지의 최신 버전을 항상 사용하고 싶을 수 있지만, 업데이트는 예상치 못한 파괴적 변경을 포함할 수 있습니다.
중요한 의존성과 이미지를 고정하여 놀라운 변경을 피하는 것을 고려하세요. 예를 들어:
variables:
ALPINE_VERSION: '3.18.6'
job1:
image: alpine:$ALPINE_VERSION # 이 경우는 예기치 않게 변경되지 않습니다.
script:
- my-test-script.sh
job2:
image: alpine:latest # 이 경우는 갑자기 변경될 수 있습니다.
script:
- my-test-script.sh
여전히 정기적으로 의존성과 이미지 업데이트를 확인해야 하며, 중요한 보안 업데이트가 있을 수 있습니다. 그런 다음, 업데이트된 이미지나 의존성이 여전히 파이프라인과 작동하는지 확인하는 프로세스의 일환으로 수동으로 버전을 업데이트할 수 있습니다.
작업 출력 확인
출력 자세히 만들기
--silent
를 사용하여 작업 로그에서 출력량을 줄이면 작업에서 문제가 발생한 원인을 파악하기 어려울 수 있습니다. 가능하면 추가 세부 정보를 위해 --verbose
를 사용하는 것을 고려하세요.
job1:
script:
- my-test-tool --silent # 이 명령이 실패하면 문제를 식별하기 어려울 수 있습니다.
- my-other-test-tool --verbose # 이 명령은 디버깅하기가 더 쉬울 가능성이 높습니다.
아티팩트로 출력 및 보고서 저장
일부 도구는 작업이 실행되는 동안에만 필요한 파일을 생성할 수 있지만, 이러한 파일의 내용은 디버깅에 사용될 수 있습니다. 나중에 분석을 위해 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
구성을 분석하여 해결할 수 있습니다. 이는 작업이 파이프라인에 추가되는 시점을 조정하는 데 사용됩니다. 같은 파이프라인에서 이 두 구성을 함께 사용하는 것은 피하는 것이 좋습니다. 두 구성의 동작이 다르기 때문에 예측하기 어렵습니다. rules
는 작업을 제어하는 데 선호되는 선택이며, only
와 except
는 더 이상 적극적으로 개발되지 않습니다.
rules
또는 only/except
구성이 predefined variables
와 같이 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
의 동작은 다르며 두 가지 간의 마이그레이션 시 예상치 못한 행동을 초래할 수 있습니다.
일반적인 if
절은 원하는 방식으로 작동하는 규칙을 작성하는 데 매우 유용할 수 있습니다.
파이프라인에 .pre
또는 .post
단계의 작업만 포함되어 있다면 실행되지 않습니다. 다른 단계에 적어도 하나의 작업이 필요합니다.
.gitlab-ci.yml
파일에 바이트 순서 표시(BOM)가 포함된 경우 예기치 않은 동작
.gitlab-ci.yml
파일 또는 다른 포함된 구성 파일에 있는 UTF-8 바이트 순서 표시(BOM)은 잘못된 파이프라인 동작을 초래할 수 있습니다. 바이트 순서 표시는 파일 파싱에 영향을 미쳐 일부 구성이 무시될 수 있습니다 - 작업이 누락되거나 변수에 잘못된 값이 있을 수 있습니다. 일부 텍스트 편집기는 설정에 따라 BOM 문자를 삽입할 수 있습니다.
파이프라인에 혼란스러운 동작이 발생하는 경우, 이를 표시할 수 있는 도구를 사용하여 BOM 문자의 존재 여부를 확인할 수 있습니다. 파이프라인 편집기는 문자를 표시할 수 없으므로 외부 도구를 사용해야 합니다. 자세한 내용은 이슈 354026를 참조하세요.
changes
키워드가 있는 작업이 예기치 않게 실행됨
작업이 파이프라인에 예기치 않게 추가되는 일반적인 이유는 changes
키워드가 특정 경우에 항상 true로 평가되기 때문입니다. 예를 들어, changes
는 예약된 파이프라인 및 태그에 대한 파이프라인 등 특정 파이프라인 유형에서 항상 true입니다.
changes
키워드는 only/except
또는 rules
와 함께 사용됩니다. 작업이 브랜치 파이프라인 또는 병합 요청 파이프라인에만 추가되도록 보장하는 if
섹션이 있는 rules
또는 only/except
구성과 함께 changes
를 사용하는 것이 좋습니다.
두 개의 파이프라인이 동시에 실행됨
커밋을 오픈된 병합 요청과 연결된 브랜치에 푸시할 때 두 개의 파이프라인이 실행될 수 있습니다. 일반적으로 하나의 파이프라인은 병합 요청 파이프라인이고 다른 하나는 브랜치 파이프라인입니다.
이 상황은 일반적으로 rules
구성에 의해 발생하며, 중복 파이프라인 방지 방법은 여러 가지가 있습니다.
파이프라인이 실행되지 않거나 잘못된 유형의 파이프라인 실행
파이프라인이 실행되기 전에 GitLab은 구성의 모든 작업을 평가하고 이를 모든 가능한 파이프라인 유형에 추가하려고 시도합니다. 평가가 끝날 때 작업이 추가되지 않으면 파이프라인은 실행되지 않습니다.
파이프라인이 실행되지 않았다면, 모든 작업에 rules
또는 only/except
가 있었고 이로 인해 파이프라인에 추가되지 못했을 가능성이 큽니다.
잘못된 파이프라인 유형이 실행되었다면, rules
또는 only/except
구성을 확인하여 작업이 올바른 파이프라인 유형에 추가되도록 해야 합니다. 예를 들어, 병합 요청 파이프라인이 실행되지 않았다면 작업이 대신 브랜치 파이프라인에 추가되었을 수 있습니다.
또한, 귀하의 workflow: rules
구성으로 인해 파이프라인이 차단되었거나 잘못된 파이프라인 유형이 허용되었을 수도 있습니다.
작업이 많은 파이프라인이 시작되지 않음
인스턴스의 정의된 CI/CD 제한보다 더 많은 작업이 있는 파이프라인은 시작되지 않습니다.
단일 파이프라인의 작업 수를 줄이려면 .gitlab-ci.yml
구성을 더 독립적인 부모-자식 파이프라인으로 나눌 수 있습니다.
파이프라인 경고
파이프라인 구성 경고는 다음과 같은 경우에 표시됩니다:
작업은 단일 작업에 대해 여러 파이프라인을 실행할 수 있습니다
경고
if
절 없이 when
절과 함께 rules
를 사용할 때 여러 파이프라인이 실행될 수 있습니다.
보통 이는 머지 요청과 연결된 브랜치에 커밋을 푸시할 때 발생합니다.
중복 파이프라인 방지를 위해 workflow: rules
를 사용하거나 실행 가능한 파이프라인을 제어하도록 규칙을 재작성하세요.
파이프라인 오류
CI/CD 파이프라인은 머지 전에 실행되어야 하며 성공해야 합니다
메시지
이 메시지는 프로젝트에서 파이프라인이 성공해야 함 설정이 활성화된 경우에 나타나며, 파이프라인이 아직 성공적으로 실행되지 않은 경우에 표시됩니다.
파이프라인이 아직 생성되지 않았거나 외부 CI 서비스의 응답을 기다리고 있는 경우에도 해당됩니다.
프로젝트에 파이프라인을 사용하지 않는 경우 파이프라인이 성공해야 함을 비활성화하여 머지 요청을 수락할 수 있습니다.
자동으로 머지할 수 있는지 확인 중
메시지
머지 요청이 자동으로 머지할 수 있는지 확인 중
메시지로 멈춰 있다면, 몇 분 후에도 사라지지 않는 경우 다음의 해결 방법 중 하나를 시도할 수 있습니다:
- 머지 요청 페이지를 새로 고침합니다.
- 머지 요청을 닫고 다시 엽니다.
-
/rebase
빠른 작업으로 머지 요청을 rebase합니다. - 머지 요청이 머지할 준비가 된 것으로 이미 확인한 경우,
/merge
빠른 작업으로 머지할 수 있습니다.
이 문제는 GitLab 15.5에서 해결되었습니다.
파이프라인 상태 확인 중
메시지
머지 요청이 아직 최신 커밋과 연결된 파이프라인이 없을 때 이 메시지는 회전하는 상태 아이콘 ()과 함께 표시됩니다. 이는 다음과 같은 이유일 수 있습니다:
- GitLab이 아직 파이프라인 생성을 완료하지 않았습니다.
- 외부 CI 서비스를 사용 중이며 GitLab이 서비스로부터 응답을 받지 못했습니다.
- 프로젝트에 CI/CD 파이프라인을 사용하지 않고 있습니다.
- 프로젝트에 CI/CD 파이프라인을 사용 중이나, 구성으로 인해 머지 요청의 소스 브랜치에서 파이프라인 실행이 차단되었습니다.
- 최신 파이프라인이 삭제되었습니다 (이는 알려진 문제입니다).
- 머지 요청의 소스 브랜치가 개인 포크에 있습니다.
파이프라인이 생성되면 메시지는 파이프라인 상태로 업데이트됩니다.
이 경우, 메시지는 파이프라인이 성공해야 함 설정이 활성화된 경우 아이콘이 끝없이 회전하며 멈출 수 있습니다. 자세한 내용은 문제 334281을 참조하세요.
프로젝트 <group/project>를 찾을 수 없거나 액세스가 거부되었습니다
메시지
이 메시지는 include
로 구성된 경우 다음과 같습니다:
- 구성에서 찾을 수 없는 프로젝트를 참조합니다.
- 파이프라인을 실행 중인 사용자가 포함된 프로젝트에 액세스할 수 없습니다.
이를 해결하려면 다음을 확인하세요:
- 프로젝트 경로가
my-group/my-project
형식이며, 저장소에 폴더를 포함하지 않는지 확인합니다. - 파이프라인을 실행하는 사용자가 포함된 파일을 포함하는 프로젝트의 멤버인지 확인합니다. 사용자는 또한 동일한 프로젝트에서 CI/CD 작업을 실행할 권한을 가져야 합니다.
YAML이 너무 큽니다
메시지
이 메시지는 YAML 구성이 너무 크거나 너무 깊게 중첩될 때 표시됩니다.
포함된 내용이 많은 YAML 파일이나 전체적으로 수천 줄에 달하는 파일은 이 메모리 한도에 도달할 가능성이 더 높습니다. 예를 들어, 200kb인 YAML 파일은 기본 메모리 한도에 도달할 가능성이 큽니다.
구성 크기를 줄이려면 다음을 수행할 수 있습니다:
-
파이프라인 편집기의 전체 구성 탭에서 확장된 CI/CD 구성의 길이를 확인하세요. 제거하거나 간소화할 수 있는 중복 구성을 찾으세요.
-
긴 또는 반복적인
script
섹션을 프로젝트의 독립 실행 스크립트로 이동하세요. -
부모 및 자식 파이프라인을 사용하여 일부 작업을 독립적인 자식 파이프라인의 작업으로 이동하세요.
자체 관리 인스턴스에서는 크기 제한을 늘릴 수 있습니다.
.gitlab-ci.yml
파일 편집 시 500
오류
포함된 구성 파일의 루프는 .gitlab-ci.yml 파일을 웹 편집기로 편집할 때 500
오류를 발생시킬 수 있습니다.
포함된 구성 파일이 서로에 대한 참조 루프를 생성하지 않도록 확인하세요.
이미지를 가져오는 데 실패했습니다
메시지
- 이 프로젝트에 CI_JOB_TOKEN 으로 접근 허용 설정은 GitLab 16.3에서 이 프로젝트 _로_의 접근 제한으로 이름이 변경되었습니다.
러너는 CI/CD 작업에서 컨테이너 이미지를 가져오려 할 때 이미지를 가져오는 데 실패했습니다
메시지를 반환할 수 있습니다.
러너는 image
로 정의된 컨테이너 이미지를 다른 프로젝트의 컨테이너 레지스트리에서 가져오는 동안 CI/CD 작업 토큰으로 인증합니다.
작업 토큰 설정이 다른 프로젝트의 컨테이너 레지스트리에 대한 접근을 방지할 경우, 러너는 오류 메시지를 반환합니다.
예를 들어:
-
WARNING:정책 “항상”으로 이미지를 가져오는 데 실패했습니다: 오류 응답: 데몬에서: registry.example.com/path/to/project에 대한 다운로드 권한 거부, 레지스트리가 존재하지 않거나 'docker login'이 필요할 수 있음: 요청된 리소스에 대한 접근이 거부되었습니다.
-
WARNING:정책 ""으로 이미지를 가져오는 데 실패했습니다: 이미지 다운로드 실패: rpc 오류: 코드 = 알 수 없음 설명 = "registry.example.com/path/to/project/image:v1.2.3"의 이미지를 가져오고 압축 해제하는 데 실패했습니다: 참조를 확인하는 데 실패했습니다 "registry.example.com/path/to/project/image:v1.2.3": 다운로드 권한 거부, 레지스트리가 존재하지 않거나 인증이 필요할 수 있습니다: 서버 메시지: insufficient_scope: 인증 실패
이 오류는 다음 두 조건이 모두 참일 때 발생할 수 있습니다:
-
이미지를 호스팅하는 개인 프로젝트에서 이 프로젝트 _로_의 접근 제한 옵션이 활성화되어 있습니다.
-
이미지를 가져오려는 작업이 개인 프로젝트의 허용 목록에 없는 프로젝트에서 실행되고 있습니다.
이 문제를 해결하려면 컨테이너 레지스트리에서 이미지를 가져오는 CI/CD 작업을 포함하는 모든 프로젝트를 대상 프로젝트의 작업 토큰 허용 목록에 추가하세요.
이 오류는 또한 다른 프로젝트의 이미지에 접근하기 위해 프로젝트 액세스 토큰을 사용하려고 할 때 발생할 수 있습니다. 프로젝트 액세스 토큰은 하나의 프로젝트로 범위가 제한되므로 다른 프로젝트의 이미지에 접근할 수 없습니다. 더 넓은 범위를 가진 다른 유형의 토큰을 사용해야 합니다.
우리 쪽에서 문제가 발생했습니다
메시지 또는 500
오류가 파이프라인 실행 시 발생하는 경우
다음과 같은 파이프라인 오류가 발생할 수 있습니다:
- 병합 요청을 푸시하거나 생성할 때
우리 쪽에서 문제가 발생했습니다
메시지. - API를 사용하여 파이프라인을 트리거할 때 발생하는
500
오류.
프로젝트가 가져온 후 내부 ID 기록이 동기화되지 않으면 이러한 오류가 발생할 수 있습니다.
이를 해결하려면 이슈 352382의 해결 방법을 참조하세요.
config should be an array of hashes
오류 메시지
다음과 유사한 오류가 발생할 수 있습니다 !reference
태그를 사용할 때
parallel:matrix
키워드와 함께:
이 GitLab CI 구성은 유효하지 않습니다: jobs:my_job_name:parallel:matrix config는 해시 배열이어야 합니다.
parallel:matrix
키워드는 동시에 여러 !reference
태그를 지원하지 않습니다.
대신 YAML 앵커를 사용해 보세요.
이슈 439828은 parallel:matrix
에서 !reference
태그 지원을 개선할 것을 제안합니다.