- 디버깅 기술
- 작업 구성 문제
- 파이프라인 경고
-
파이프라인 오류
A CI/CD pipeline must run and be successful before merge
메시지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
메시지 - 파이프라인 실행 중
Something went wrong on our end
메시지 또는500
에러 발생 config should be an array of hashes
에러 메시지
CI/CD 파이프라인 디버깅
GitLab은 CI/CD 구성을 디버깅하는 데 도움이 되는 여러 도구를 제공합니다.
파이프라인 문제를 해결할 수 없는 경우 다음에서 도움을 받을 수 있습니다:
- GitLab 커뮤니티 포럼
- GitLab 지원팀
특정 CI/CD 기능에 문제가 있는 경우 해당 기능의 관련 문제 해결 섹션을 참조하세요.
- 캐싱.
- CI/CD 작업 토큰.
- 컨테이너 레지스트리.
- 도커.
- 다운스트림 파이프라인.
- 환경.
- GitLab 러너.
- ID 토큰.
- 작업.
- 작업 아티팩트.
- 병합 요청 파이프라인, 병합된 결과 파이프라인, 그리고 병합 트레인.
- 파이프라인 편집기.
- 변수.
-
YAML
includes
키워드. -
YAML
script
키워드.
디버깅 기술
구문 검증
문제의 초기 원인은 잘못된 구문일 수 있습니다. 파이프라인에 yaml invalid
뱃지가 표시되고 구문 또는 형식 문제가 발견되면 실행이 시작되지 않습니다.
.gitlab-ci.yml
을 파이프라인 편집기에서 편집
파이프라인 편집기는 다음을 포함하는 권장 편집 경험입니다.
- 적용된 키워드만 사용하도록 하는 코드 완성 제안.
- 자동 구문 강조 표시 및 유효성 검사.
-
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 유효성 검증 도구로 구문 확인
CI 유효성 검증 도구를 사용하여 CI/CD 구성 스니펫의 구문이 올바른지 확인할 수 있습니다. 전체 .gitlab-ci.yml
파일이나 개별 작업 구성을 붙여넣어 기본 구문을 확인합니다.
프로젝트에 .gitlab-ci.yml
파일이 있으면 CI 유효성 검증 도구를 사용하여 전체 파이프라인 생성을 시뮬레이션할 수도 있습니다. 구성 구문의 깊은 확인을 수행합니다.
파이프라인 이름 사용
모든 파이프라인 유형에 이름을 지정하는 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
#### 버전 고정
의존성 또는 이미지의 최신 버전을 항상 사용하려 할지라도, 업데이트는 갑자기 중단될 수 있는 파괴적인 변경 사항을 포함할 수 있습니다. 예상치 못한 변경 사항을 피하기 위해 주요 의존성 및 이미지를 고정하는 것을 고려하세요. 예시:
```yaml
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
경고: 파이프라인에 접근할 수 있는 모든 사용자가 볼 수 있기 때문에 artifacts에 토큰, 암호 또는 기타 민감한 정보를 저장해서는 안됩니다.
작업 명령 로컬에서 실행하기
Rancher Desktop 또는 유사한 대체 제품과 같은 도구를 사용하여 작업의 컨테이너 이미지를 로컬 기기에서 실행할 수 있습니다. 그런 다음, 컨테이너에서 작업의 script
명령을 실행하고 동작을 확인할 수 있습니다.
실패한 작업의 원인을 해결하기 위한 루트 원인 분석
GitLab Duo 채팅의 GitLab Duo 루트 원인 분석을 사용하여 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
절은 원하는 대로 동작하는 규칙을 작성하는 방법에 대한 예제로 매우 유용할 수 있습니다.
파이프라인에 .pre
또는 .post
단계의 작업만 포함되어 있는 경우, 파이프라인이 실행되지 않습니다. 다른 단계에 적어도 하나의 다른 작업이 있어야 합니다.
.gitlab-ci.yml
파일에 바이트 순서 표시 (BOM) 포함 시 예상치 않은 동작
.gitlab-ci.yml
파일 또는 다른 포함된 구성 파일에 UTF-8 바이트 순서 표시 (BOM)가 포함되어 있으면 잘못된 파이프라인 동작을 일으킬 수 있습니다. 바이트 순서 표시는 파일의 구문 분석에 영향을 미쳐 일부 구성을 무시할 수 있습니다. 작업이 누락될 수 있으며 변수는 잘못된 값을 가질 수 있습니다.
일부 텍스트 편집기는 구성이 잘못된 경우 BOM 문자를 삽입할 수 있습니다.
파이프라인이 혼란스러운 동작을 하는 경우, BOM 문자를 표시할 수 있는 도구를 사용하여 확인할 수 있습니다. 파이프라인 편집기에서는 문자를 표시할 수 없으므로 외부 도구를 사용해야 합니다. 자세한 내용은 issue 354026를 참조하세요.
changes
키워드가 있는 작업이 예상치 않게 실행될 때
작업이 예상치 않게 파이프라인에 추가되는 일반적인 이유는 changes
키워드가 특정 경우에 항상 true로 평가되기 때문입니다. 예를 들어, 스케줄된 파이프라인 또는 태그용 파이프라인을 포함한 특정 파이프라인에서는 항상 changes
가 true입니다.
changes
키워드는 only/changes
, except/changes
와 함께 사용됩니다. changes
는 rules
또는 only/except
구성의 if
섹션과 사용하는 것이 권장됩니다. 이를 통해 작업이 브랜치 파이프라인 또는 병합 요청 파이프라인에만 추가되도록 할 수 있습니다.
```
… (The rest of the text exceeds the character limit)
두 개의 파이프라인이 동시에 실행됨
커밋을 브랜치에 푸시할 때 두 개의 파이프라인이 실행될 수 있습니다. 보통 한 개의 파이프라인은 병합 요청 파이프라인이고, 다른 하나는 브랜치 파이프라인입니다.
이 상황은 보통 rules
구성으로 인해 발생하며, 중복 파이프라인 방지하는 여러 가지 방법이 있습니다.
파이프라인이 실행되지 않거나 잘못된 유형의 파이프라인이 실행됨
파이프라인이 실행되기 전에 GitLab은 구성의 모든 작업을 평가하고 모든 가능한 파이프라인 유형에 추가하려고 합니다. 평가가 끝날 때 파이프라인에 작업이 추가되지 않으면 파이프라인이 실행되지 않습니다.
파이프라인이 실행되지 않았다면, 모든 작업이 파이프라인에 추가되는 것을 막는 rules
또는 only/except
가 있었을 가능성이 높습니다.
잘못된 파이프라인 유형이 실행된 경우, 일치하는 rules
또는 only/except
구성을 확인하여 작업이 올바른 파이프라인 유형에 추가되도록 합니다. 예를 들어, 병합 요청 파이프라인이 실행되지 않았다면 작업이 브랜치 파이프라인에 추가된 것일 수 있습니다.
또한 파이프라인을 차단하거나 잘못된 파이프라인 유형을 허용한 것일 수 있습니다.
많은 작업을 가진 파이프라인이 시작하지 못함
인스턴스에서 정의한 CI/CD 제한보다 많은 작업을 가진 파이프라인은 시작되지 않습니다.
단일 파이프라인에 있는 작업의 수를 줄이려면 .gitlab-ci.yml
구성을 더 많은 독립적인 상위-하위 파이프라인으로 분할할 수 있습니다.
파이프라인 경고
파이프라인 구성 경고는 다음 시점에 표시됩니다:
- CI Lint 도구로 구성을 검증할 때
- 수동으로 파이프라인 실행시
Job may allow multiple pipelines to run for a single action
경고
if
절이 없는 rules
와 함께 when
절을 사용하여 파이프라인을 실행하면 여러 개의 파이프라인이 실행될 수 있습니다. 일반적으로 이는 병합 요청이 연결된 브랜치에 커밋을 푸시하는 경우 발생합니다.
중복 파이프라인 방지를 위해 workflow: rules
를 사용하거나 어떤 파이프라인을 실행할 수 있는지 제어하기 위해 규칙을 다시 작성할 수 있습니다.
파이프라인 오류
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
빠른 조치를 사용하여 병합
이 이슈는 GitLab 15.5에서 해결되었습니다.
Checking pipeline status
메시지
이 메시지는 최신 커밋에 연결된 파이프라인이 아직 없을 때 회전하는 상태 아이콘()과 함께 표시됩니다. 이는 다음 사항에 따라 발생할 수 있습니다:
- GitLab이 아직 파이프라인을 완전히 생성하지 못했을 때
- 외부 CI 서비스를 사용하고 GitLab이 서비스로부터 응답을 받지 못한 경우
- 프로젝트에서 CI/CD 파이프라인을 사용하지 않는 경우
- 프로젝트에서 CI/CD 파이프라인을 사용하지만 구성이 병합 요청의 소스 브랜치에서 파이프라인 실행을 막은 경우
- 최신 파이프라인이 삭제된 경우(이는 알려진 이슈입니다)
- 병합 요청의 소스 브랜치가 비공개 포크인 경우
파이프라인이 생성된 후에 메시지가 파이프라인 상태로 업데이트됩니다.
이러한 경우 중 일부에서 Pipelines must succeed 설정이 활성화되어 있는 경우 메시지가 끝없이 회전할 수 있습니다. 자세한 내용은 이슈 334281을 참조하십시오.
Project <group/project> not found or access denied
메시지
이 메시지는 구성에 include
가 추가되고 다음 중 하나인 경우에 표시됩니다:
- 찾을 수 없는 프로젝트를 참조하는 구성
- 파이프라인을 실행 중인 사용자가 포함된 파일에 대한 액세스 권한이 없는 경우
이를 해결하려면 다음을 확인합니다:
- 프로젝트 경로가
my-group/my-project
형식이며 저장소의 어떤 폴더도 포함하지 않는지 확인합니다. - 파이프라인을 실행 중인 사용자가 포함된 파일을 포함하는 프로젝트의 멤버인지 확인합니다. 사용자는 또한 동일한 프로젝트에서 CI/CD 작업을 실행할 권한을 가지고 있어야 합니다.
The parsed YAML is too big
메시지
이 메시지는 YAML 구성이 너무 크거나 너무 깊게 중첩되었을 때 표시됩니다. 많은 수의 include와 전체적으로 수천 줄의 YAML 파일은 이 메모리 제한에 도달할 가능성이 높습니다. 예를 들어, 200KB인 YAML 파일은 기본 메모리 제한에 도달할 가능성이 높습니다.
구성 크기를 줄이려면 다음을 할 수 있습니다:
- 파이프라인 에디터의 전체 구성 보기 탭에서 확장된 CI/CD 구성의 길이를 확인합니다. 제거하거나 간소화할 수 있는 중복 구성을 찾습니다.
- 프로젝트의 긴 또는 반복적인
script
섹션을 독립된 스크립트로 이동합니다. - 일부 작업을 독립적인 하위 파이프라인의 작업으로 이동하기 위해 상위 및 하위 파이프라인을 사용합니다.
셀프 매니지드 인스턴스에서는 크기 제한을 늘릴 수 있습니다.
.gitlab-ci.yml
파일을 편집할 때 500
에러 발생
포함된 구성 파일의 루프는 .gitlab-ci.yml
파일을 웹 편집기로 편집할 때 500
에러를 발생시킬 수 있습니다. 웹 편집기를 사용하여 .gitlab-ci.yml
파일을 편집할 때 포함된 구성 파일의 루프가 발생하지 않도록 해주세요.
이미지를 끌어오지 못하는 Failed to pull image
메시지
- GitLab 16.3에서 프로젝트에 대한 CI_JOB_TOKEN으로의 액세스를 허용하는 설정이 이제 이 프로젝트의 액세스를 제한으로 이름이 변경되었습니다.
CI/CD 작업에서 다른 프로젝트의 컨테이너 레지스트리에서 image
로 정의된 컨테이너 이미지를 가져오려고 시도할 때 러너에서 Failed to pull 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 message: insufficient_scope: authorization failed
이러한 오류는 두 가지 조건이 모두 참일 때 발생할 수 있습니다:
- 비공개 프로젝트에서 이제 이 프로젝트의 액세스를 제한 옵션이 활성화되어 있는 경우.
- 이미지를 가져오려는 작업이 해당 이미지가 허용 목록에 없는 프로젝트에서 실행 중인 경우.
이 문제를 해결하려면 컨테이너 레지스트리에서 이미지를 가져오는 CI/CD 작업이 있는 모든 프로젝트를 대상 프로젝트의 작업 토큰 허용 목록에 추가하세요.
또한 이러한 오류는 다른 프로젝트의 이미지에 액세스하기 위해 프로젝트 액세스 토큰을 사용하려고 할 때 발생할 수 있습니다. 프로젝트 액세스 토큰은 한 프로젝트에 대해 스코프가 지정되어 있기 때문에 다른 프로젝트의 이미지에 액세스할 수 없습니다. 더 넓은 스코프의 다른 토큰 유형을 사용해야 합니다.
파이프라인 실행 중 Something went wrong on our end
메시지 또는 500
에러 발생
다음과 같은 파이프라인 오류를 받을 수 있습니다:
- 푸시하거나 머지 요청을 생성할 때
Something went wrong on our end
메시지가 표시될 수 있습니다. - API를 사용하여 파이프라인을 트리거하려고 할 때
500
에러가 발생할 수 있습니다.
이러한 오류는 프로젝트가 가져온 후 내부 ID 레코드가 동기화되지 않아 발생할 수 있습니다.
이 문제를 해결하려면 issue 352382의 해결책을 참조하세요.
config should be an array of hashes
에러 메시지
parallel:matrix
와 함께 !reference
태그를 사용할 때 다음과 유사한 오류가 발생할 수 있습니다:
This GitLab CI configuration is invalid: jobs:my_job_name:parallel:matrix config should be an array of hashes.
parallel:matrix
키워드는 동시에 여러 !reference
태그를 지원하지 않습니다. 대신 YAML 앵커를 사용해 보세요.
Issue 439828은 parallel:matrix
에서 !reference
태그의 지원을 개선하는 것을 제안합니다.