SQ Official Doc Link: https://docs.sonarqube.org/display/SONAR/Webhooks

Table of Contents

웹훅(webhooks)은 컴퓨트 엔진(compute engine)을 통해 분석 보고서를 처리한 후, 사용자가 입력한 외부 HTTP(S) URL로 데이터를 포스트(POST) 방식으로 전달합니다. 일반적으로 SonarQube 프로젝트의 품질 게이트 상태를 외부 도구에 알리기 위해 웹훅을 사용할 수 있습니다.

HTTP(S) 호출은:

백그라운드 태스크(Background Task)의 상태와 관계없이 생성됩니다.
POST 방식을 사용하며, JSON 문서로 payload를 구성합니다.
UTF-8 인코딩 방식을 사용하며, "application/json" 컨텐트 타입을 가집니다.

설정

최대 10개의 웹훅을 설정할 수 있습니다. 웹훅을 설정하려면 Administration > Configuration > General Settings > Webhooks 메뉴를 사용합니다.

추가적으로 global 레벨에서 10개의 웹훅을 설정할 수 있습니다. 설정된 웹훅은 동시에 실행됩니다.

Payload 형태

웹훅의 Payload는 JSON 문서입니다. 이 JSON 문서에서 다음을 확인할 수 있습니다:

분석이 수행되는 시기: "analysedAt"
분석 대상 프로젝트의 고유 식별자: "project"
기준 품질 게이트 및 상태: "qualityGate"
분석 대상 프로젝의 품질 게이트 상태: "qualityGate.status"
백그라운드 태스크 상태 및 식별자: "status" & "taskId"
사용자 정의 속성: "properties"

Example

{
    "analysedAt": "2016-11-18T10:46:28+0100",
    "project": {
        "key": "org.sonarqube:example",
        "name": "Example"
    },
    "properties": {
    },
    "qualityGate": {
        "conditions": [
            {
                "errorThreshold": "1",
                "metric": "new_security_rating",
                "onLeakPeriod": true,
                "operator": "GREATER_THAN",
                "status": "OK",
                "value": "1"
            },
            {
                "errorThreshold": "1",
                "metric": "new_reliability_rating",
                "onLeakPeriod": true,
                "operator": "GREATER_THAN",
                "status": "OK",
                "value": "1"
            },
            {
                "errorThreshold": "1",
                "metric": "new_maintainability_rating",
                "onLeakPeriod": true,
                "operator": "GREATER_THAN",
                "status": "OK",
                "value": "1"
            },
            {
                "errorThreshold": "80",
                "metric": "new_coverage",
                "onLeakPeriod": true,
                "operator": "LESS_THAN",
                "status": "NO_VALUE"
            }
        ],
        "name": "SonarQube way",
        "status": "OK"
    },
    "status": "SUCCESS",
    "taskId": "AVh21JS2JepAEhwQ-b3u"
}

웹훅에 추가 파라미터를 사용하려면?

sonar.analysis.* 패턴을 사용해 SonarQube Scanner에 속성을 추가하면, 해당 속성들은 자동적으로 payload의 "properties" 섹션에 반영됩니다.

예:

sonar-scanner -Dsonar.analysis.scmRevision=628f5175ada0d685fd7164baa7c6382c1f25cab4 -Dsonar.analysis.buildNumber=12345

Payload에는 다음이 추가됩니다:

"properties": {
  "sonar.analysis.scmRevision": "628f5175ada0d685fd7164baa7c6382c1f25cab4",
  "sonar.analysis.buildNumber": "12345"
}

전달 결과

현재 UI를 통해 웹훅 전달 결과를 확인할 방법은 없습니다. Web Services를 통해서만 결과를 확인할 수 있으나, 해당 서비스는 베타 상태이기 때문에 특별한 공지 없이 변경될 수 있습니다. 응답 기록은 30일 후 삭제됩니다.

api/webhooks/deliveries
api/webhooks/delivery

웹훅을 등록/제거할 수 있는 Web API는 제공되지 않습니다. 웹훅의 등록/삭제는 UI를 통해서만 수행할 수 있습니다.

웹훅을 통해 사용자 인증(credential)은 제공할 수 없습니다.

참고

대상 URL은 10초 이내에 응답을 해야하며, 그렇지 못하는 경우 웹훅 전송 결과는 실패로 인식합니다.
HTTP 헤더 "X-SonarQube-Project"는 project key 값과 함께 전달되어, 해당 프로젝트를 쉽게 식별할 수 있습니다.