외부 상태 확인

요약

상태 확인은 외부 요구 사항의 상태를 조회하기 위해 외부 시스템에 보내는 API 호출입니다. 머지 리퀘스트 데이터를 서드파티 도구로 보내는 상태 확인을 만들 수 있습니다. 이 통합을 사용하면 ServiceNow 같은 서드파티 워크플로 도구나 직접 선택한 도구와 연동할 수 있습니다.

상태 확인은 외부 요구 사항의 상태를 조회하기 위해 외부 시스템에 보내는 API 호출입니다.

머지 리퀘스트 데이터를 서드파티 도구로 보내는 상태 확인을 만들 수 있습니다. 사용자가 머지 리퀘스트를 생성, 변경, 종료하면 GitLab이 알림을 보냅니다. 그러면 사용자나 자동화된 워크플로가 GitLab 외부에서 머지 리퀘스트의 상태를 업데이트할 수 있습니다.

이 통합을 사용하면 ServiceNow 같은 서드파티 워크플로 도구나 직접 선택한 도구와 연동할 수 있습니다. 서드파티 도구는 해당 상태를 응답으로 보냅니다. 이 상태는 머지 리퀘스트 안에 머지를 막지 않는 위젯으로 표시되어, 머지 리퀘스트 작성자나 검토자가 머지 리퀘스트 화면에서 바로 상태를 확인할 수 있습니다.

머지 리퀘스트 상태 확인은 프로젝트별로 구성합니다. 프로젝트 간에는 공유되지 않습니다.

상태 확인이 2분을 넘겨 pending 상태로 남아 있으면 실패합니다.

접근 권한#

외부 상태 확인 응답은 다음 사용자가 확인할 수 있습니다.

프로젝트에서 Reporter, Developer, Maintainer 또는 Owner 권한을 가진 사용자
프로젝트 공개 범위가 internal인 경우 머지 리퀘스트를 볼 수 있는 인증된 모든 사용자

즉, 프로젝트가 internal이면 머지 리퀘스트에 접근할 수 있는 로그인 사용자는 모두 외부 상태 확인 응답을 볼 수 있습니다.

사용 사례, 기능 탐색, 개발 일정에 관한 자세한 내용은 에픽 3869를 참고합니다.

모든 상태 확인을 통과하지 않은 머지 리퀘스트의 머지 차단#

기본적으로 프로젝트의 머지 리퀘스트는 외부 상태 확인이 실패해도 머지할 수 있습니다. 외부 상태 확인이 실패했을 때 머지 리퀘스트의 머지를 차단하려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
Status checks must succeed 체크박스를 선택합니다.
Save changes를 선택합니다.

라이프사이클#

외부 상태 확인은 비동기 워크플로로 동작합니다. 머지 리퀘스트는 다음과 같은 경우 외부 서비스로 머지 리퀘스트 웹훅 페이로드를 보냅니다.

머지 리퀘스트가 업데이트, 종료, 재오픈, 승인, 승인 취소 또는 머지된 경우.
머지 리퀘스트의 소스 브랜치에 코드가 푸시된 경우.

페이로드에는 상태 확인의 id, name, external_url을 담은 external_approval_rule 객체도 포함됩니다.

Mermaid 다이어그램 (8줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Workflow for external status checks
    accDescr: Merge request sends payload to external service and receives status check response
Merge request-&gt;&gt;+External service: Merge request payload
External service--&gt;&gt;-Merge request: Status check response
Note over External service,Merge request: Response includes SHA at HEAD</code></pre></details></div>

페이로드를 받은 외부 서비스는 필요한 처리를 수행한 뒤 REST API를 사용해 머지 리퀘스트에 응답을 보낼 수 있습니다.
머지 리퀘스트는 소스 브랜치의 현재 HEAD를 가리키지 않는 응답에 대해 409 Conflict 오류를 반환합니다. 따라서 외부 서비스가 오래된 커밋을 처리하고 응답해도 안전합니다.
외부 상태 확인의 상태는 다음과 같습니다.

pending - 기본 상태입니다. 머지 리퀘스트가 외부 서비스로부터 아직 응답을 받지 않았습니다.
passed - 외부 서비스의 응답을 받았고 외부 서비스가 승인했습니다.
failed - 외부 서비스의 응답을 받았고 외부 서비스가 거부했습니다.

GitLab 외부에서 상황이 바뀌면 API로 외부 상태 확인의 상태를 설정할 수
있습니다. 머지 리퀘스트 웹훅 페이로드가 먼저 전송되기를 기다릴 필요는 없습니다.
상태 확인 서비스 보기#
머지 리퀘스트 설정에서 프로젝트에 추가된 상태 확인 서비스 목록을 보려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
Status checks까지 스크롤합니다. 이 목록에는 서비스 이름, API URL, 대상 브랜치,
HMAC 인증 상태가 표시됩니다.


브랜치 규칙 설정에서도 상태 확인 서비스 목록을 볼 수 있습니다.
상태 확인 서비스 추가 또는 업데이트#
상태 확인 서비스 추가#
Status checks 하위 섹션에서 Add status check 버튼을 선택합니다.
그러면 Add status check 양식이 표시됩니다.

양식을 작성하고 Add status check 버튼을 선택하면 새 상태 확인이 만들어집니다.
상태 확인은 모든 새 머지 리퀘스트에 적용되며, 기존 머지 리퀘스트에는 소급 적용되지 않습니다.
상태 확인 서비스 업데이트#
Status checks 하위 섹션에서 편집할 상태 확인 옆의 Edit (✏️)를
선택합니다.
그러면 Update status check 양식이 표시됩니다.

Note
HMAC 공유 비밀 값은 확인하거나 수정할 수 없습니다. 공유 비밀을 변경하려면 외부 상태 확인을 삭제한 뒤 새 공유 비밀 값으로 다시 만듭니다.

상태 확인을 업데이트하려면 양식의 값을 변경하고 Update status check를 선택합니다.
상태 확인 업데이트는 모든 새 머지 리퀘스트에 적용되며, 기존 머지 리퀘스트에는 소급 적용되지 않습니다.
양식 값#
자주 발생하는 양식 오류는 아래 문제 해결 섹션을 참고합니다.
서비스 이름#
이름에는 영숫자 값을 사용할 수 있으며 반드시 입력해야 합니다. 이름은 프로젝트 안에서
고유해야 합니다.
확인할 API#
이 필드에는 URL이 필요하며 HTTP 또는 HTTPS 프로토콜을 사용해야 합니다.
전송 중인 머지 리퀘스트 데이터를 보호하려면 HTTPS 사용을 권장합니다.
URL은 반드시 입력해야 하며 프로젝트 안에서 고유해야 합니다.
대상 브랜치#
상태 확인을 단일 브랜치로 제한하려면
이 필드에서 그 범위를 지정합니다.

브랜치 목록은 프로젝트의 보호된 브랜치에서 채워집니다.
브랜치 목록을 스크롤할 수 있으며, 브랜치가 많아 찾는 브랜치가
바로 보이지 않을 때는 검색 상자를 사용합니다. 검색은
영숫자 세 글자를 입력해야
시작됩니다.
상태 확인을 모든 머지 리퀘스트에 적용하려면
All branches 옵션을 선택합니다.
HMAC 공유 비밀#
HMAC 인증은 요청 변조를 방지하고
요청이 정당한 출처에서 왔음을 보장합니다.
상태 확인 서비스 삭제#
Status checks 하위 섹션에서 삭제할 상태 확인 옆의 Remove ([remove])를
선택합니다.
그러면 Remove status check? 대화 상자가 표시됩니다.

상태 확인 삭제를 완료하려면 Remove status check 버튼을
선택해야 합니다. 이 작업은 상태 확인을 영구적으로 삭제하며
복구할 수 없습니다.
상태 확인 위젯#
상태 확인 위젯은 머지 리퀘스트에 표시되며 다음 상태를 나타냅니다.

pending ([status-neutral]): GitLab이 외부 상태 확인의 응답을 기다리는 중입니다.
success ([status-success]) 또는 failed ([status-failed]): GitLab이 외부 상태 확인의 응답을 받았습니다.

대기 중인 상태 확인이 있으면 위젯은 success 또는 failed 응답을 받을 때까지 몇 초 간격으로 업데이트를 조회합니다.
실패한 상태 확인을 다시 시도하려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Code > Merge requests를 선택하고 머지 리퀘스트를 찾습니다.
머지 리퀘스트 리포트 섹션으로 스크롤한 뒤 드롭다운 목록을 펼쳐 외부 상태 확인 목록을 표시합니다.
실패한 외부 상태 확인 행에서 Retry ([retry])를 선택합니다. 해당 상태 확인은 다시 pending 상태가 됩니다.

조직에 따라 외부 상태 확인을 통과하지 못한 머지 리퀘스트의 머지를 허용하지 않는 정책이
있을 수 있습니다. 다만 위젯에 표시되는 내용은 정보 제공
목적입니다.
Note
GitLab은 관련 외부 서비스가 외부 상태 확인을 올바르게 처리한다는 점을
보장하지 않습니다.

문제 해결#
중복 값 오류#
Name is already taken
---
External API is already in use by another status check

프로젝트 단위로 상태 확인은 이름이나 API URL을 한 번만 사용할 수 있습니다.
이 오류는 해당 상태 확인의 이름이나 API URL이 이미 이 프로젝트의 상태 확인에
사용되고 있다는 뜻입니다.
현재 상태 확인에 다른 값을 지정하거나 기존 상태 확인의 값을
변경해야 합니다.
유효하지 않은 URL 오류#
Please provide a valid URL

확인할 API 필드에는 HTTP 또는 HTTPS 프로토콜을 사용하는 URL을 입력해야 합니다.
이 조건을 충족하도록 필드 값을 변경해야 합니다.
브랜치 목록 조회 또는 검색 중 오류#
Unable to fetch branches list, please close the form and try again

브랜치 조회 API에서 예상하지 못한 응답을 받았습니다.
안내대로 양식을 닫았다가 다시 열거나 페이지를 새로 고칩니다. 이 오류는 일시적이지만,
계속된다면 GitLab 상태 페이지에서 광범위한 장애가 있는지 확인합니다.
상태 확인 로드 실패#
Failed to load status checks

외부 상태 확인 API에서 예상하지 못한 응답을 받았습니다.
다음을 수행합니다.

이 오류가 일시적일 수 있으므로 페이지를 새로 고칩니다.
문제가 계속되면 GitLab 상태 페이지에서
광범위한 장애가 있는지 확인합니다.

관련 주제#

외부 상태 확인 API

홈/GitLab/사용자/프로젝트/Merge requests/외부 상태 확인

`외부 상태 확인`

GitLab v19.5

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기
번역일: 2026-10-15

요약
상태 확인은 외부 요구 사항의 상태를 조회하기 위해 외부 시스템에 보내는 API 호출입니다. 머지 리퀘스트 데이터를 서드파티 도구로 보내는 상태 확인을 만들 수 있습니다. 이 통합을 사용하면 ServiceNow 같은 서드파티 워크플로 도구나 직접 선택한 도구와 연동할 수 있습니다.

상태 확인은 외부 요구 사항의 상태를 조회하기 위해 외부 시스템에 보내는 API 호출입니다.


머지 리퀘스트 데이터를 서드파티 도구로 보내는 상태 확인을 만들 수 있습니다.
사용자가 머지 리퀘스트를 생성, 변경, 종료하면 GitLab이 알림을 보냅니다. 그러면 사용자나 자동화된 워크플로가
GitLab 외부에서 머지 리퀘스트의 상태를 업데이트할 수 있습니다.
이 통합을 사용하면 ServiceNow 같은 서드파티 워크플로 도구나 직접 선택한 도구와
연동할 수 있습니다. 서드파티 도구는 해당 상태를 응답으로 보냅니다.
이 상태는 머지 리퀘스트 안에 머지를 막지 않는 위젯으로 표시되어,
머지 리퀘스트 작성자나 검토자가 머지 리퀘스트 화면에서 바로 상태를
확인할 수 있습니다.
머지 리퀘스트 상태 확인은 프로젝트별로 구성합니다. 프로젝트 간에는 공유되지 않습니다.
상태 확인이 2분을 넘겨 pending 상태로 남아 있으면 실패합니다.
접근 권한#
외부 상태 확인 응답은 다음 사용자가 확인할 수 있습니다.

프로젝트에서 Reporter, Developer, Maintainer 또는 Owner 권한을 가진 사용자
프로젝트 공개 범위가 internal인 경우 머지 리퀘스트를 볼 수 있는 인증된 모든 사용자

즉, 프로젝트가 internal이면 머지 리퀘스트에 접근할 수 있는 로그인 사용자는 모두 외부 상태 확인 응답을 볼 수 있습니다.
사용 사례, 기능 탐색, 개발 일정에 관한 자세한 내용은
에픽 3869를 참고합니다.
모든 상태 확인을 통과하지 않은 머지 리퀘스트의 머지 차단#
기본적으로 프로젝트의 머지 리퀘스트는 외부 상태 확인이 실패해도 머지할 수 있습니다. 외부 상태 확인이 실패했을 때 머지 리퀘스트의 머지를 차단하려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
Status checks must succeed 체크박스를 선택합니다.
Save changes를 선택합니다.

라이프사이클#
외부 상태 확인은 비동기 워크플로로 동작합니다. 머지 리퀘스트는 다음과 같은 경우 외부 서비스로 머지 리퀘스트 웹훅 페이로드를 보냅니다.

머지 리퀘스트가 업데이트, 종료, 재오픈, 승인, 승인 취소 또는 머지된 경우.
머지 리퀘스트의 소스 브랜치에 코드가 푸시된 경우.

페이로드에는 상태 확인의 id, name, external_url을 담은 external_approval_rule 객체도 포함됩니다.
Mermaid 다이어그램 (8줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Workflow for external status checks
    accDescr: Merge request sends payload to external service and receives status check response
Merge request-&gt;&gt;+External service: Merge request payload
External service--&gt;&gt;-Merge request: Status check response
Note over External service,Merge request: Response includes SHA at HEAD</code></pre></details></div>

페이로드를 받은 외부 서비스는 필요한 처리를 수행한 뒤 REST API를 사용해 머지 리퀘스트에 응답을 보낼 수 있습니다.
머지 리퀘스트는 소스 브랜치의 현재 HEAD를 가리키지 않는 응답에 대해 409 Conflict 오류를 반환합니다. 따라서 외부 서비스가 오래된 커밋을 처리하고 응답해도 안전합니다.
외부 상태 확인의 상태는 다음과 같습니다.

pending - 기본 상태입니다. 머지 리퀘스트가 외부 서비스로부터 아직 응답을 받지 않았습니다.
passed - 외부 서비스의 응답을 받았고 외부 서비스가 승인했습니다.
failed - 외부 서비스의 응답을 받았고 외부 서비스가 거부했습니다.

GitLab 외부에서 상황이 바뀌면 API로 외부 상태 확인의 상태를 설정할 수
있습니다. 머지 리퀘스트 웹훅 페이로드가 먼저 전송되기를 기다릴 필요는 없습니다.
상태 확인 서비스 보기#
머지 리퀘스트 설정에서 프로젝트에 추가된 상태 확인 서비스 목록을 보려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
Status checks까지 스크롤합니다. 이 목록에는 서비스 이름, API URL, 대상 브랜치,
HMAC 인증 상태가 표시됩니다.


브랜치 규칙 설정에서도 상태 확인 서비스 목록을 볼 수 있습니다.
상태 확인 서비스 추가 또는 업데이트#
상태 확인 서비스 추가#
Status checks 하위 섹션에서 Add status check 버튼을 선택합니다.
그러면 Add status check 양식이 표시됩니다.

양식을 작성하고 Add status check 버튼을 선택하면 새 상태 확인이 만들어집니다.
상태 확인은 모든 새 머지 리퀘스트에 적용되며, 기존 머지 리퀘스트에는 소급 적용되지 않습니다.
상태 확인 서비스 업데이트#
Status checks 하위 섹션에서 편집할 상태 확인 옆의 Edit (✏️)를
선택합니다.
그러면 Update status check 양식이 표시됩니다.

Note
HMAC 공유 비밀 값은 확인하거나 수정할 수 없습니다. 공유 비밀을 변경하려면 외부 상태 확인을 삭제한 뒤 새 공유 비밀 값으로 다시 만듭니다.

상태 확인을 업데이트하려면 양식의 값을 변경하고 Update status check를 선택합니다.
상태 확인 업데이트는 모든 새 머지 리퀘스트에 적용되며, 기존 머지 리퀘스트에는 소급 적용되지 않습니다.
양식 값#
자주 발생하는 양식 오류는 아래 문제 해결 섹션을 참고합니다.
서비스 이름#
이름에는 영숫자 값을 사용할 수 있으며 반드시 입력해야 합니다. 이름은 프로젝트 안에서
고유해야 합니다.
확인할 API#
이 필드에는 URL이 필요하며 HTTP 또는 HTTPS 프로토콜을 사용해야 합니다.
전송 중인 머지 리퀘스트 데이터를 보호하려면 HTTPS 사용을 권장합니다.
URL은 반드시 입력해야 하며 프로젝트 안에서 고유해야 합니다.
대상 브랜치#
상태 확인을 단일 브랜치로 제한하려면
이 필드에서 그 범위를 지정합니다.

브랜치 목록은 프로젝트의 보호된 브랜치에서 채워집니다.
브랜치 목록을 스크롤할 수 있으며, 브랜치가 많아 찾는 브랜치가
바로 보이지 않을 때는 검색 상자를 사용합니다. 검색은
영숫자 세 글자를 입력해야
시작됩니다.
상태 확인을 모든 머지 리퀘스트에 적용하려면
All branches 옵션을 선택합니다.
HMAC 공유 비밀#
HMAC 인증은 요청 변조를 방지하고
요청이 정당한 출처에서 왔음을 보장합니다.
상태 확인 서비스 삭제#
Status checks 하위 섹션에서 삭제할 상태 확인 옆의 Remove ([remove])를
선택합니다.
그러면 Remove status check? 대화 상자가 표시됩니다.

상태 확인 삭제를 완료하려면 Remove status check 버튼을
선택해야 합니다. 이 작업은 상태 확인을 영구적으로 삭제하며
복구할 수 없습니다.
상태 확인 위젯#
상태 확인 위젯은 머지 리퀘스트에 표시되며 다음 상태를 나타냅니다.

pending ([status-neutral]): GitLab이 외부 상태 확인의 응답을 기다리는 중입니다.
success ([status-success]) 또는 failed ([status-failed]): GitLab이 외부 상태 확인의 응답을 받았습니다.

대기 중인 상태 확인이 있으면 위젯은 success 또는 failed 응답을 받을 때까지 몇 초 간격으로 업데이트를 조회합니다.
실패한 상태 확인을 다시 시도하려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Code > Merge requests를 선택하고 머지 리퀘스트를 찾습니다.
머지 리퀘스트 리포트 섹션으로 스크롤한 뒤 드롭다운 목록을 펼쳐 외부 상태 확인 목록을 표시합니다.
실패한 외부 상태 확인 행에서 Retry ([retry])를 선택합니다. 해당 상태 확인은 다시 pending 상태가 됩니다.

조직에 따라 외부 상태 확인을 통과하지 못한 머지 리퀘스트의 머지를 허용하지 않는 정책이
있을 수 있습니다. 다만 위젯에 표시되는 내용은 정보 제공
목적입니다.
Note
GitLab은 관련 외부 서비스가 외부 상태 확인을 올바르게 처리한다는 점을
보장하지 않습니다.

문제 해결#
중복 값 오류#
Name is already taken
---
External API is already in use by another status check

프로젝트 단위로 상태 확인은 이름이나 API URL을 한 번만 사용할 수 있습니다.
이 오류는 해당 상태 확인의 이름이나 API URL이 이미 이 프로젝트의 상태 확인에
사용되고 있다는 뜻입니다.
현재 상태 확인에 다른 값을 지정하거나 기존 상태 확인의 값을
변경해야 합니다.
유효하지 않은 URL 오류#
Please provide a valid URL

확인할 API 필드에는 HTTP 또는 HTTPS 프로토콜을 사용하는 URL을 입력해야 합니다.
이 조건을 충족하도록 필드 값을 변경해야 합니다.
브랜치 목록 조회 또는 검색 중 오류#
Unable to fetch branches list, please close the form and try again

브랜치 조회 API에서 예상하지 못한 응답을 받았습니다.
안내대로 양식을 닫았다가 다시 열거나 페이지를 새로 고칩니다. 이 오류는 일시적이지만,
계속된다면 GitLab 상태 페이지에서 광범위한 장애가 있는지 확인합니다.
상태 확인 로드 실패#
Failed to load status checks

외부 상태 확인 API에서 예상하지 못한 응답을 받았습니다.
다음을 수행합니다.

이 오류가 일시적일 수 있으므로 페이지를 새로 고칩니다.
문제가 계속되면 GitLab 상태 페이지에서
광범위한 장애가 있는지 확인합니다.

관련 주제#

외부 상태 확인 API