Jira¶
Jira 알림 대상은 Webhook(외부 알림을 수신하는 HTTP 엔드포인트)을 통해 Guance 알림을 JSON 형식으로 Jira 수신 프로세스에 전송합니다. Jira에서 필드 매핑과 처리 작업을 구성하여 프로젝트 팀이 알림을 처리하도록 할 수 있습니다.
이 문서에서는 Jira Cloud Automation의 Incoming webhook을 예로 듭니다. 이슈가 속한 프로젝트, 유형, 생성 또는 업데이트 규칙, 중복 제거 및 상태 유지 관리는 모두 Jira 자동화 규칙에 의해 제어됩니다.
Jira에서 수신 규칙 구성¶
대상 프로젝트의 자동화 규칙을 편집할 수 있는 권한이 필요합니다.
- 대상 Jira 프로젝트의 Automation으로 이동하여 자동화 규칙을 생성합니다.
- Incoming webhook 트리거를 추가합니다.
- Create issue 등의 처리 작업을 추가하고 프로젝트와 이슈 유형을 선택합니다. 최초 연결 테스트에서는 먼저 고정 요약을 사용할 수 있습니다(예: “모니터링 알림 테스트”). 수신이 확인되면 실제 알림에 따라 요약을
{{webhookData.title}}로, 설명을{{webhookData.message}}로 매핑합니다. - Save flow without enabling을 선택하고 규칙 이름을 입력한 후 저장합니다.
- Incoming webhook 트리거를 다시 열고 No issues from the webhook을 선택한 다음 Webhook URL과 Secret을 복사합니다. 트리거 구성을 저장하고 규칙을 활성화합니다.
Jira는 webhookData를 사용하여 요청의 JSON 필드를 읽습니다. 하나의 알림에는 여러 이벤트가 포함될 수 있으므로 비즈니스 요구에 따라 전체 알림 단위로 이슈를 생성하거나 events를 순회하며 각 이벤트를 처리하고, 이벤트 컨텍스트, 백링크 및 monitor_checker_links의 모니터 링크를 이슈 필드에 매핑하십시오.
수신 엔드포인트와 Secret 구성은 Jira Incoming webhook 공식 문서를 참고하고, 필드 매핑은 Jira 공식 알림 연동 예시를 참고하십시오.
Guance에서 알림 대상 생성¶
모니터링 > 알림 대상 관리 > 알림 대상 생성으로 이동하여 Jira를 선택합니다.
- 목록 및 알림 정책에서 알림 대상을 식별하는 데 사용할 이름을 입력합니다. 이름은 현재 워크스페이스 내에서 고유해야 하며 최대 200자입니다.
- Webhook 주소에 Jira에서 제공한 전체 HTTPS URL을 입력하며, POST 요청을 실제로 수신하는 최종 주소를 사용합니다.
- 인증 방식에서 Secret을 선택하고 Jira에서 생성한 Secret을 입력합니다. 시스템은
X-Automation-Webhook-Token요청 헤더를 통해 이 값을 전송합니다. - 수신 측 요구 사항에 따라 기타 인증 방식 및 사용자 지정 요청 헤더를 설정합니다.
- 테스트 알림 전송을 클릭하고 미리 본 후 전송을 확인합니다. 테스트는 실제로 Jira 규칙을 호출하며, 후속 작업은 규칙에 따라 실행됩니다.
- Jira의 Audit log로 이동하여 이번 규칙 실행 기록이 있는지 확인하고, 알림 필드와 이슈 처리 결과를 검토합니다.
- 작업 권한을 구성하고 저장을 확인합니다.
- 알림 정책에서 해당 알림 대상을 선택하고, 전송할 이벤트 등급과 범위를 구성합니다.
기타 인증 방식 및 사용자 지정 요청 헤더¶
Jira Cloud Automation의 기본 Incoming webhook은 Secret을 사용합니다. 게이트웨이, 플러그인 또는 자체 구축 수신 서비스를 연동할 때는 해당 엔드포인트에서 실제로 지원하는 프로토콜에 따라 인증 방식을 선택합니다.
| 인증 방식 | 입력 내용 | 사용 설명 |
|---|---|---|
| Secret | Secret | 위 Jira Cloud Automation 엔드포인트에 적용됩니다. |
| Basic | 사용자 이름, 비밀번호 | 수신 측 규약에 따라 자격 증명을 제공하며, 사용자 이름은 비어 있지 않아야 하고 콜론을 포함하지 않아야 합니다. |
| Bearer Token | Token | 기존 Access Token의 원래 값을 입력하면 시스템이 Bearer 접두사를 추가합니다. 토큰이 만료되거나 취소된 후에는 업데이트하십시오. |
| API Key | 요청 헤더 이름, API Key | 수신 측 규약에 따라 요청 헤더 이름과 전체 값을 입력합니다. Content-Type은 예약된 이름입니다. |
| 인증 없음 | — | 수신 측 요구 사항에 따라 사용자 지정 요청 헤더를 설정합니다. |
필요에 따라 사용자 지정 요청 헤더를 활성화하고 수신 측에서 요구하는 키와 값을 추가합니다. 헤더 이름은 대소문자를 구분하지 않고 중복 제거되며, 선택한 인증 방식에서 생성된 요청 헤더가 동일한 이름의 사용자 지정 헤더보다 우선합니다. Content-Type은 application/json으로 고정되고 Accept의 기본값은 application/json입니다.
자격 증명 편집¶
저장된 객체를 편집할 때 동일한 주소, 인증 방식 및 ID에서는 Secret, 비밀번호, Token 또는 API Key를 비워 두면 기존 값이 유지되고, 새 값을 입력하면 대체됩니다. 주소, 인증 방식, 사용자 이름 또는 API Key 요청 헤더 이름을 변경한 후에는 해당 자격 증명을 입력해야 합니다.
사용자 지정 요청 헤더 값은 암호화되어 저장됩니다. 위 구성이 동일하게 유지되는 경우 저장된 동일한 이름의 요청 헤더 값을 비워 두면 유지되고, 새 값을 입력하면 대체됩니다. 행을 삭제하면 해당 헤더가 제거됩니다. 요청 헤더를 추가하거나 이름을 변경한 경우, 그리고 위 구성을 변경한 후에는 전체 요청 헤더 값을 입력하십시오.
테스트에는 현재 양식의 유효한 구성이 사용됩니다. 저장 후에는 이후 알림에 새 구성이 사용됩니다. Jira Secret을 다시 생성한 후에는 알림 대상의 Secret도 함께 업데이트하십시오.
알림 내용 및 알림 집계¶
Jira 알림 대상은 간단한 HTTP 요청의 알림 집계 형식을 따르며, 일반, 규칙 집계 및 지능형 집계 알림을 지원합니다. 수신 측은 다음 필드에 따라 알림을 파싱합니다.
| 필드 | 의미 |
|---|---|
title, message, status |
현재 알림의 제목, 본문 및 상태입니다. |
events |
이벤트 목록입니다. 일반 알림에는 이벤트 하나가 포함되고, 집계 알림에는 해당 이벤트 그룹이 포함되며 이벤트 컨텍스트와 백링크가 유지됩니다. |
workspace_uuid, workspace_name |
이벤트가 속한 워크스페이스의 ID와 이름입니다. |
monitor_checker_links |
규칙 집계 및 지능형 집계 알림에서 모니터 이름과 이벤트 목록 링크입니다. |
알림 정책은 어떤 이벤트가 동일한 알림을 구성하는지 결정합니다. 알림 내용 구성이 완료되면 전송이 시작됩니다. 명시적 지연이 구성된 알림은 지정된 시간에 전송됩니다.
테스트 및 문제 해결¶
테스트 알림의 필드는 수신 측이 실제로 수신한 JSON을 기준으로 합니다. 엔드포인트 및 인증 테스트를 완료한 후 실제 일반, 집계 알림으로 title, events 등 필드의 매핑을 검증하십시오. 최초 테스트에서 고정 요약을 사용하면 테스트 샘플에 title이 없을 때 이슈 생성이 실패하는 것을 방지할 수 있습니다.
수신 엔드포인트가 HTTP 2xx를 반환하는 것은 요청이 완료되었음을 의미할 뿐입니다. Jira의 최신 Incoming webhook은 Secret이 잘못되었거나 규칙이 존재하지 않는 경우에도 HTTP 200을 반환할 수 있습니다. 연동 성공 여부는 Audit log의 이번 실행 기록, 필드 파싱 및 후속 작업 결과를 기준으로 판단하십시오.
| 현상 | 확인 방법 |
|---|---|
| 요청은 완료되었지만 Audit log에 이번 기록이 없음 | 규칙이 활성화되어 있는지, URL과 Secret이 동일한 트리거에서 제공되었는지 확인합니다. Secret을 다시 생성한 경우 알림 대상도 함께 업데이트하십시오. |
| 규칙이 실행되었지만 이슈 필드가 비어 있음 | webhookData 필드 경로를 확인하고, 실제 일반 및 집계 알림으로 각각 파싱을 검증합니다. |
| 이슈 수가 예상과 다름 | 규칙이 전체 알림 단위로 실행되는지, 아니면 events의 이벤트 단위로 실행되는지, 그리고 Jira 측의 중복 제거 규칙을 확인합니다. |
| 전송 실패 | 최종 HTTPS 주소, 인증서, 네트워크 연결성 및 수신 측 권한을 확인합니다. HTTP 3xx 리디렉션은 전송 실패로 처리됩니다. |
추가 문제 해결 방법은 Jira Incoming webhook 공식 테스트 가이드를 참고하십시오.