다운스트림 파이프라인 문제 해결

다운스트림 파이프라인(트리거 job으로 시작되는 하위 파이프라인)을 쓰다 보면 "트리거 job이 실패하더라", "변수가 제대로 전달되지 않네" 하는 상황을 만나게 되죠. 이 글은 GitLab CI에서 마주치기 쉬운 다운스트림 파이프라인 오류들을 모아, 각각 어떤 원인이고 어떻게 해결하는지 설명할게요.

출처: 문서

본문

트리거 job이 실패하고 멀티 프로젝트 파이프라인이 생성되지 않음

멀티 프로젝트 파이프라인에서 다음 경우에 트리거 job이 실패하고 다운스트림 파이프라인이 생성되지 않아요.

다운스트림 프로젝트를 찾을 수 없는 경우
업스트림 파이프라인을 생성한 사용자가 다운스트림 프로젝트에서 파이프라인을 생성할 권한이 없는 경우
다운스트림 파이프라인이 보호된 브랜치를 대상으로 하는데, 사용자가 보호된 브랜치에 대해 파이프라인을 실행할 권한이 없는 경우 — 자세한 내용은 보호된 브랜치의 파이프라인 보안을 참고하세요.

다운스트림 프로젝트에서 권한 문제가 있는 사용자가 누구인지 확인하려면 Rails 콘솔에서 다음 명령으로 트리거 job을 확인하고 user_id 속성을 살펴볼 수 있어요.

Ci::Bridge.find(<job_id>)

파이프라인이 실행될 때 자식 파이프라인의 job이 생성되지 않음

상위 파이프라인이 머지 리퀘스트 파이프라인이라면, 자식 파이프라인은 job이 실행되도록 workflow:rules 또는 rules를 사용해야 해요.

규칙(rules) 구성이 없거나 잘못되어 자식 파이프라인에서 실행할 job이 하나도 없다면:

자식 파이프라인 시작에 실패해요.
상위 파이프라인의 트리거 job이 downstream pipeline can not be created, the resulting pipeline would have been empty 메시지와 함께 실패해요. rules 구성을 검토해 보세요.

$ 문자가 포함된 변수가 다운스트림 파이프라인에 제대로 전달되지 않음

CI/CD 변수를 다운스트림 파이프라인에 전달할 때 $$를 사용해 CI/CD 변수의 $ 문자를 이스케이프할 수 없어요. 다운스트림 파이프라인은 여전히 $를 변수 참조의 시작으로 취급하기 때문이죠.

UI에서 변수를 구성할 때 CI/CD 변수 확장 방지를 켜거나, variables:expand 키워드를 사용해 변수 값이 확장되지 않도록 설정할 수 있어요. 이렇게 설정한 변수는 $가 변수 참조로 해석되지 않은 채 다운스트림 파이프라인에 전달됩니다.

Ref가 모호함 (Ref is ambiguous)

브랜치와 같은 이름의 태그로는 멀티 프로젝트 파이프라인을 트리거할 수 없어요. 이 경우 다운스트림 파이프라인 생성이 downstream pipeline can not be created, Ref is ambiguous 오류와 함께 실패합니다.

브랜치 이름과 일치하지 않는 태그 이름으로만 멀티 프로젝트 파이프라인을 트리거하세요.

데이터 무결성 실패로 트리거 job 실패

이 오류는 job 처리 중 예상치 못한 예외가 발생했음을 나타내요. 원인과 해결 단계는 오류: 데이터 무결성 실패를 참고하세요.

업스트림 파이프라인에서 job 아티팩트를 다운로드할 때 403 Forbidden 오류

CI/CD job 토큰은 파이프라인이 실행되는 프로젝트로 범위가 지정돼요. 따라서 다운스트림 파이프라인의 job 토큰은 기본적으로 업스트림 프로젝트에 접근하는 데 사용할 수 없습니다.

이 문제를 해결하려면 다운스트림 프로젝트를 job 토큰 범위 허용 목록에 추가하세요.

오류: needs:need pipeline should be a string

동적 자식 파이프라인에서 needs:pipeline:job을 사용할 때 다음 오류를 받을 수 있어요.

Unable to run pipeline
- jobs:<job_name>:needs:need pipeline should be a string

이 오류는 파이프라인 ID가 문자열이 아닌 정수로 파싱될 때 발생합니다. 해결하려면 파이프라인 ID를 따옴표로 감싸세요.

rspec:
  needs:
    - pipeline: "$UPSTREAM_PIPELINE_ID"
      job: dependency-job
      artifacts: true

더 알아보기 (Learn more)

다운스트림 파이프라인을 구성하는 기본 원리를 다시 확인하고 싶다면 다운스트림 파이프라인 문서를, job 토큰 범위와 관련한 보안 설정은 CI job 토큰 문서를 참고하세요.