외부 커밋 상태

외부 커밋 상태 (External commit statuses)

Jenkins나 CircleCI 같은 외부 CI/CD 시스템이나 커스텀 배포 도구가 GitLab 파이프라인과 연동되도록 해주는 기능이 외부 커밋 상태예요. 외부 시스템이 커밋 상태를 GitLab에 다시 올리면, 그 상태 결과가 머지 리퀘스트와 커밋 화면에서 CI/CD 잡 옆에 함께 표시됩니다.

출처: 문서

본문

외부 시스템이 Commits API로 커밋 상태를 올리면, GitLab은 그 상태를 기존 파이프라인에 추가하거나, 없으면 새 파이프라인을 만들어 담아요.

파이프라인 선택

외부 시스템에서 커밋 상태를 올리면 find-or-create 방식이 사용됩니다.

  1. GitLab은 주어진 커밋 SHA와 ref에 대해 가장 최근의 non-archived CI 파이프라인을 찾아요. pipeline_id 파라미터를 포함하면 특정 파이프라인을 직접 검색할 수도 있습니다.
  2. 적절한 파이프라인을 찾으면 그 파이프라인에 새 잡 상태를 덧붙여요. 기존 파이프라인에 추가된 잡의 CI_PIPELINE_SOURCE는 해당 파이프라인의 소스(예: push, merge_request_event)를 따릅니다.
  3. 적절한 파이프라인이 없으면 잡을 담을 새 파이프라인을 만들고, 이때 CI_PIPELINE_SOURCE는 external이 돼요.

외부 잡 상태는 다른 GitLab CI/CD 스테이지와 분리된 external 스테이지에 나타납니다.

같은 커밋에 중복 파이프라인이 존재하면 외부 상태가 어디 놓일지가 애매해져요. GitLab은 newest_first로 가장 최신 파이프라인을 선택하지만, 파이프라인이 동시에 생성되면 외부 상태가 예상치 못한 파이프라인에 나타나거나 머지 리퀘스트 화면에 보이지 않을 수 있어요. 중복 파이프라인을 피하려면 workflow rules을 설정하거나, pipeline_id로 파이프라인을 직접 지정하세요.

잡 업데이트와 재시도

외부 시스템에서 커밋 상태를 올리면:

  • 대상 파이프라인에 name, user, sha가 같은 running 또는 pending 잡이 이미 있으면 상태만 업데이트돼요. name이 같은 잡을 다른 사용자가 업데이트하면 잡이 재시도됩니다. 그러면 새 잡이 생기고 기존 잡은 현재 파이프라인에서 숨겨져요.
  • running 또는 pending이 아닌 잡을 name은 같고 status는 다르게(예: failed로 표시된 잡에 success 보내기) 재시도할 수 있어요. 그러면 새 잡이 생기고 기존 잡은 현재 파이프라인에서 숨겨집니다.
  • 서로 다른 외부 서비스가 고유한 잡 name을 사용하면 같은 SHA와 파이프라인에 잡을 추가할 수 있어요.

이미 SHA/ref 조합에 대해 업데이트가 진행 중이면 409 오류가 반환됩니다. 이 오류를 처리하려면 요청을 재시도하세요.

문제 해결

머지 리퀘스트에 외부 상태가 보이지 않을 때

외부 CI 상태가 머지 리퀘스트 파이프라인에 나타나지 않으면:

  1. 같은 커밋에 대해 머지 리퀘스트 파이프라인과 브랜치 파이프라인이 모두 도는지 확인하세요.
  2. workflow rules이 중복 파이프라인을 막는지 확인합니다.
  3. 외부 시스템이 올바른 ref로 상태를 올리는지 확인하세요.
  4. 커밋이 머지 리퀘스트와 연결되어 있으면, API 호출이 머지 리퀘스트의 소스 브랜치에 있는 커밋을 대상으로 하는지 확인합니다.

자세한 내용은 중복 파이프라인 피하기를 참고하세요.

더 알아보기

외부 도구를 GitLab과 묶을 때 가장 어려운 부분이 중복 파이프라인 문제예요. workflow rules로 중복을 예방하거나 pipeline_id로 대상을 명시하는 방법을 먼저 익혀두면, 외부 시스템이 올린 상태가 엉뚱한 파이프라인에 들어가는 일을 피할 수 있어요. 다음으로는 workflow rules와 Commits API 문서를 함께 보는 걸 추천해요.