• 디버깅 기법
  • 구문 확인
    • .gitlab-ci.yml을 파이프라인 편집기로 편집
    • 로컬에서 .gitlab-ci.yml 편집
    • CI Lint 도구로 구문 확인
  • 파이프라인 이름 사용
  • CI/CD 변수
    • 변수 확인
    • CLI 명령에 플래그 추가를 위한 변수 사용
  • 의존성
    • 의존성 버전 확인
    • 버전 고정
  • 작업 출력 확인
    • 출력을 상세하게 만들기
    • 출력 및 보고서를 아티팩트로 저장
  • 작업 명령 로컬에서 실행
• 작업 구성 문제
  • 작업 또는 파이프라인이 예상대로 실행되지 않음
  • .gitlab-ci.yml 파일에 바이트 순서 표시 (BOM)가 포함되어 예기치 않은 동작
  • changes 키워드를 가진 작업이 예상치 않게 실행됨
  • 두 개의 파이프라인이 동시에 실행됨
  • 파이프라인이 실행되지 않거나 잘못된 유형의 파이프라인이 실행됨
  • 많은 작업이 포함된 파이프라인이 시작에 실패함
• 파이프라인 경고
  • 작업이 단일 작업에 대해 여러 파이프라인을 실행할 수 있음 경고
• 문제 해결
  • Merge하기 전에 CI/CD 파이프라인이 실행되고 성공해야 함 메시지
  • 자동 Merge 가능성을 확인 중 메시지
  • 파이프라인 상태 확인 메시지
  • 프로젝트 <group/project>를 찾을 수 없거나 액세스가 거부되었습니다 메시지
  • 구문 분석된 YAML이 너무 큼 메시지
  • .gitlab-ci.yml 파일을 편집할 때 500 오류
  • 이미지를 다운로드하지 못했다는 Failed to pull image 메시지
  • 파이프라인 실행 시 Something went wrong on our end 메시지 또는 500 오류

CI/CD 파이프라인 디버깅

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

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

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

디버깅 기법

구문 확인

문제의 초기 원인은 부정확한 구문일 수 있습니다. 파이프라인은 잘못된 구문이나 형식 문제를 발견하면 yaml invalid 배지가 나타나고 실행되지 않을 수 있습니다.

.gitlab-ci.yml을 파이프라인 편집기로 편집

파이프라인 편집기는 다음을 포함하는 권장 편집 환경입니다:

• 허용된 키워드만 사용하도록 보장하는 코드 완성 제안.
• 자동 구문 강조 및 유효성 검사.
• .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: "Merge Request 파이프라인"
    - 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 명령을 실행하고 동작을 확인할 수 있습니다.

작업 구성 문제

rules 또는 only/except 구성의 동작을 분석하여 일반적인 파이프라인 문제를 해결할 수 있습니다. 이 두 구성을 동일한 파이프라인에서 사용하면 안 됩니다. 이들은 다르게 동작하기 때문에 파이프라인이 이러한 혼합 동작으로 실행되는 것을 예측하기 어렵습니다. rules은 작업을 제어하기 위한 우선 선택 사항입니다. only 및 except는 더 이상 적극적으로 개발되지 않습니다.

사전 정의된 변수와 같은 rules 또는 only/except 구성을 사용하는 경우 먼저 이를 확인해야 합니다.

작업 또는 파이프라인이 예상대로 실행되지 않음

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 문자의 존재 여부를 확인할 수 있습니다. 파이프라인 편집기는 이 문자를 표시할 수 없으므로 외부 도구를 사용해야 합니다. 자세한 내용은 이슈 35402를 참조하십시오.

changes 키워드를 가진 작업이 예상치 않게 실행됨

작업이 예상치 않게 파이프라인에 추가되는 일반적인 이유는 changes 키워드가 특정한 경우에 항상 true로 평가되기 때문입니다. 예를 들어, changes는 예약된 파이프라인 및 태그 파이프라인을 포함한 특정 파이프라인 유형에서는 항상 true입니다.

changes 키워드는 only/except 또는 rules와 함께 사용됩니다. changes는 rules나 only/except 구성의 if 섹션과 함께 사용하여 작업이 브랜치 파이프라인이나 Merge Request 파이프라인에만 추가되도록 보장하는 것이 좋습니다.

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

커밋을 브랜치에 푸시하면 해당 브랜치에 연결된 열린 Merge Request이 있을 때 두 개의 파이프라인이 실행될 수 있습니다. 보통 하나의 파이프라인은 Merge Request 파이프라인이고, 다른 하나는 브랜치 파이프라인입니다.

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

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

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

파이프라인이 실행되지 않았다면, 모든 작업이 파이프라인에 추가되지 못하도록 하는 rules 또는 only/except 때문일 가능성이 높습니다.

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

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

많은 작업이 포함된 파이프라인이 시작에 실패함

인스턴스에서 정의된 CI/CD 제한 사항보다 더 많은 작업을 가진 파이프라인은 시작하지 못합니다.

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

파이프라인 경고

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

• CI Lint 툴로 구성 유효성을 확인하는 경우
• 매뉴얼으로 파이프라인을 실행하는 경우

작업이 단일 작업에 대해 여러 파이프라인을 실행할 수 있음 경고

when 절이 없는 rules와 함께 rules을 사용하는 경우 하나의 동작에 여러 파이프라인이 실행될 수 있습니다. 보통 이는 브랜치에 커밋을 푸시할 때 열린 Merge Request과 관련된 경우에 발생합니다.

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

문제 해결

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

• 캐싱
• CI/CD 작업 토큰
• 컨테이너 레지스트리
• 도커
• 하위 파이프라인
• 환경
• GitLab Runner
• ID 토큰
• 작업
• 작업 제어
• 작업 아티팩트
• Merge Request 파이프라인, Merge된 결과 파이프라인, 및 Merge Train
• 파이프라인 편집기
• 변수
• YAML includes 키워드
• YAML script 키워드

그렇지 않은 경우, 알려진 상태 메시지 및 오류 메시지에 대한 다음 문제 해결 섹션을 검토하십시오.

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

프로젝트에서 Pipelines must succeed 설정이 활성화되어 있고 파이프라인이 아직 성공적으로 실행되지 않은 경우 또는 아직 생성되지 않은 경우 또는 외부 CI 서비스를 기다리는 경우 표시됩니다. 프로젝트에서 파이프라인을 사용하지 않는 경우 Pipelines must succeed 설정을 비활성화하여 Merge Request을 수락할 수 있습니다.

자동 Merge 가능성을 확인 중 메시지

Merge Request이 몇 분 이후에 사라지지 않는 자동 Merge 가능성을 확인 중 메시지로 멈춘 경우 다음 중 하나를 시도할 수 있습니다:

• Merge Request 페이지를 새로 고침합니다.
• Merge Request을 닫고 다시 엽니다.
• /rebase 빠른 동작을 사용하여 Merge Request을 다시 베이스로 설정합니다.
• 이미 Merge Request이 준비되었음을 확인했다면, /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 작업을 실행할 권한도 필요합니다.

구문 분석된 YAML이 너무 큼 메시지

이 메시지는 YAML 구성이 너무 크거나 너무 깊게 중첩될 때 표시됩니다. 포함된 구성의 수가 많고 전체적으로 수천 줄인 YAML 파일은 이러한 메모리 제한에 부딪힐 가능성이 더 높습니다. 예를 들어, 200 kb인 YAML 파일은 기본 메모리 제한에 부딪힐 가능성이 높습니다.

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

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

자체 호스팅된 인스턴스에서는 CI/CD 구성 YAML 파일의 최대 크기 및 깊이를 증가시킬 수 있습니다.

.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 작업에서 컨테이너 이미지를 가져오려고 시도할 때 러너가 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 message: insufficient_scope: authorization failed
  

이러한 오류는 다음이 모두 참인 경우 발생할 수 있습니다:

• 이 프로젝트로의 액세스 제한 옵션이 비공개 프로젝트에서 활성화되어 있음.
• 이미지를 가져오려는 작업이 허용 디렉터리에 나열되어 있지 않은 프로젝트에서 실행됨.

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

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

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

다음과 같은 파이프라인 오류가 발생할 수 있습니다:

• 커밋을 푸시하거나 Merge Request을 생성할 때 Something went wrong on our end 메시지가 표시될 수 있습니다.
• API를 사용하여 파이프라인을 트리거할 때 500 오류가 발생할 수 있습니다.

이러한 오류는 프로젝트를 가져온 후 내부 ID의 레코드가 동기화되지 않으면 발생할 수 있습니다.

이 문제를 해결하려면 issue #352382의 Workaround을 참조하세요.