guardia-itsm/cicd/docs/04_itsm_integration.md

GUARDiA ITSM 연동 가이드

버전: 1.0.0
최종 수정: 2026-05-25

---

1. 연동 아키텍처

GUARDiA Messenger
    │  !build <session_id>
    ▼
GUARDiA ITSM API
    │  POST /api/vibe/{id}/build
    │  (Jenkins REST API 호출)
    ▼
Jenkins Server
    │  파이프라인 실행
    │
    ├── Stage 1~7 실행
    │
    └── Stage 8: ITSM Callback
            │  POST /api/vibe/callback
            ▼
        GUARDiA ITSM
            │  SR 상태 = COMPLETED
            │
            ├── 고객 이메일 발송
            └── 메신저 결과 통보

---

2. Jenkins → ITSM Callback API

2-1. 엔드포인트

POST /api/vibe/callback
Content-Type: application/json
Authorization: Bearer <ITSM_API_TOKEN>

2-2. 요청 바디

{
    "session_id": "42",
    "sr_id": "SR-2026-001234",
    "status": "COMPLETED",
    "stage": "ITSM Callback",
    "message": "배포 완료 (빌드 #15)",
    "build_number": "15",
    "build_url": "http://jenkins.agency.go.kr:8080/job/my-app/15/",
    "deploy_env": "prd",
    "timestamp": "2026-05-25T14:30:00Z",
    "logs": {
        "build": "빌드 성공 (45초)",
        "test": "테스트 통과 (120/120)",
        "deploy": "배포 완료 → /opt/apps/my-app",
        "health_check": "HTTP 200 OK"
    }
}

2-3. 응답

// 성공
{
    "ok": true,
    "sr_id": "SR-2026-001234",
    "sr_status": "COMPLETED",
    "notified": ["email", "messenger"]
}

// 실패
{
    "ok": false,
    "error": "세션을 찾을 수 없습니다."
}

2-4. 상태값 목록

status	설명	SR 상태 변경
BUILDING	빌드 진행 중	IN_PROGRESS
TESTING	테스트 진행 중	IN_PROGRESS
DEPLOYING	배포 진행 중	IN_PROGRESS
COMPLETED	배포 완료	COMPLETED
FAILED	파이프라인 실패	FAILED
UNSTABLE	테스트 불안정	IN_PROGRESS
PENDING_APPROVAL	운영 배포 승인 대기	PENDING
ROLLED_BACK	롤백 완료	IN_PROGRESS

---

3. ITSM → Jenkins 빌드 트리거 API

3-1. Jenkins REST API 호출 형식

# 파라미터 있는 빌드 트리거
curl -X POST \
    "http://jenkins.agency.go.kr:8080/job/${JOB_NAME}/buildWithParameters" \
    --user "itsm-bot:${JENKINS_TOKEN}" \
    --data-urlencode "ITSM_SESSION_ID=${SESSION_ID}" \
    --data-urlencode "ITSM_SR_ID=${SR_ID}" \
    --data-urlencode "DEPLOY_ENV=${DEPLOY_ENV}" \
    --data-urlencode "TARGET_SERVER=${TARGET_SERVER}"

3-2. GUARDiA ITSM core/cicd.py

import httpx

JENKINS_URL = os.getenv("JENKINS_URL", "http://jenkins.agency.go.kr:8080")
JENKINS_USER = os.getenv("JENKINS_USER", "itsm-bot")
JENKINS_TOKEN = os.getenv("JENKINS_TOKEN", "")

async def trigger_pipeline(
    job_name: str,
    session_id: int,
    sr_id: str,
    deploy_env: str = "dev",
    target_server: str = "",
) -> dict:
    url = f"{JENKINS_URL}/job/{job_name}/buildWithParameters"
    auth = (JENKINS_USER, JENKINS_TOKEN)
    params = {
        "ITSM_SESSION_ID": str(session_id),
        "ITSM_SR_ID": sr_id,
        "DEPLOY_ENV": deploy_env,
        "TARGET_SERVER": target_server,
    }
    async with httpx.AsyncClient(timeout=30) as client:
        resp = await client.post(url, auth=auth, params=params)
        resp.raise_for_status()
    # 큐 번호는 Location 헤더에서 추출
    location = resp.headers.get("Location", "")
    queue_id = location.rstrip("/").split("/")[-1] if location else None
    return {"queued": True, "queue_id": queue_id}

---

4. 환경 변수 설정

4-1. GUARDiA ITSM (.env)

# Jenkins 연동
JENKINS_URL=http://jenkins.agency.go.kr:8080
JENKINS_USER=itsm-bot
JENKINS_TOKEN=<API Token>
JENKINS_CALLBACK_URL=http://itsm.agency.go.kr:8000/api/vibe/callback

# 기본 Jenkins Job 이름 (프로젝트별로 재정의 가능)
JENKINS_DEFAULT_JOB=guardia-default-pipeline

4-2. Jenkins (JCasC or Manage Jenkins)

# jenkins.yaml 참고
globalNodeProperties:
  - envVars:
      env:
        - key: ITSM_URL
          value: "http://itsm.agency.go.kr:8000"
        - key: ITSM_CALLBACK_URL
          value: "http://itsm.agency.go.kr:8000/api/vibe/callback"

4-3. Jenkins Credentials 등록 (ITSM Token)

Kind:     Secret text
ID:       itsm-api-token
Secret:   <GUARDiA ITSM에서 발급한 API 토큰>

---

5. 봇 명령어 ↔ Jenkins 파이프라인 매핑

봇 명령어	Jenkins Job	설명
!build <session_id>	{project}-build	빌드 + 테스트만
!deploy <session_id> dev	{project}-deploy	개발 서버 배포
!deploy <session_id> prd	{project}-deploy	운영 서버 배포 (승인 필요)
!rollback <session_id> <버전>	{project}-rollback	이전 버전 롤백

---

6. SR 상태 전환 흐름

OPEN
  │ !vibe 명령
  ▼
IN_PROGRESS (바이브 코딩)
  │ !build 명령
  ▼
IN_PROGRESS (빌드/테스트)
  │ Jenkins 빌드 완료
  ▼
IN_PROGRESS (배포)
  │ Jenkins 배포 완료 + 헬스체크 통과
  ▼
COMPLETED
  │ 자동 이메일 + 메신저 발송

실패 시:

IN_PROGRESS
  │ Jenkins FAILED 콜백
  ▼
FAILED
  │ 롤백 자동 실행 (설정 시)
  ▼
IN_PROGRESS (수동 조치 대기)

---

7. 알림 포맷

7-1. 배포 완료 메신저 알림

✅ [SR-2026-001234] 배포 완료

📌 프로젝트: my-app
🌿 브랜치: main
🏗️  빌드: #15
🌐 환경: 운영 (prd)
⏱️  소요 시간: 4분 23초

✔️ 빌드: 성공
✔️ 테스트: 120/120 통과
✔️ 배포: /opt/apps/my-app
✔️ 헬스체크: HTTP 200 OK

승인자: 홍길동, 김철수
담당자: 이영희

7-2. 배포 실패 메신저 알림

❌ [SR-2026-001234] 배포 실패

📌 프로젝트: my-app
🏗️  빌드: #15
💥 실패 단계: Health Check

원인: 서비스 응답 없음 (3회 재시도 후 타임아웃)
🔄 자동 롤백 완료 → 빌드 #14로 복원

조치 필요: http://jenkins.agency.go.kr:8080/job/my-app/15/

---

8. 연동 테스트

# 1. ITSM → Jenkins 트리거 테스트
curl -X POST \
    "http://jenkins.agency.go.kr:8080/job/test-pipeline/buildWithParameters" \
    --user "itsm-bot:<TOKEN>" \
    --data-urlencode "ITSM_SESSION_ID=1" \
    --data-urlencode "ITSM_SR_ID=SR-TEST-001" \
    --data-urlencode "DEPLOY_ENV=dev"

# 2. Jenkins → ITSM 콜백 테스트
curl -X POST "http://itsm.agency.go.kr:8000/api/vibe/callback" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <TOKEN>" \
    -d '{
        "session_id": "1",
        "sr_id": "SR-TEST-001",
        "status": "COMPLETED",
        "message": "연동 테스트 성공",
        "build_number": "1"
    }'