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. 요청 바디

```json
{
    "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. 응답

```json
// 성공
{
    "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 호출 형식

```bash
# 파라미터 있는 빌드 트리거
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

```python
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)

```bash
# 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)

```yaml
# 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. 연동 테스트

```bash
# 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"
    }'
```