CI/CD Feedback Agent

API Reference

API 명세

백엔드(FastAPI)가 노출하는 엔드포인트 명세입니다. 외부 시스템이 호출하는 webhook, 운영자가 쓰는 admin API, 재실행용 agent 엔드포인트, 외부 공개 spec fetch 로 구성됩니다.

현재는 prototype 브랜치 기준 — Jira 연계와 Slack 송신은 제외돼 있고, 결과 메시지는 대시보드에 직접 렌더됩니다.

01

공통 규약

모든 엔드포인트가 공유하는 응답 봉투·에러·인증·처리 방식입니다.

응답 봉투 (envelope)

정상 응답은 { "data": ..., "job_id"? } 형태로 감쌉니다. 목록은 data 에 배열이 담깁니다.

에러 형식

에러는 { "error": { "code", "message" } } + HTTP 4xx/5xx. message 는 한국어 고정입니다.

인증

/admin/* 는 아키텍트 전용(require_admin). 프로토타입에선 AUTH_ENABLED=false 로 미들웨어를 우회합니다.

비동기 처리

Webhook · agent 진입점은 즉시 202 로 JobAck 를 반환하고, 실제 그래프 실행은 BackgroundTasks 로 위임합니다.

02

Webhooks

외부 배포 도구가 CI/CD Feedback Agent 를 호출하는 진입점. 매 이벤트마다 jobs row 가 생성됩니다.

외부 → 백엔드

webhooks
POST/webhooks/jenkins202

Jenkins post-build 훅. 빌드 결과 페이로드를 받아 Job 을 기록하고 백그라운드로 분석 그래프를 실행합니다.

bodyJenkinsBuildEvent (jobName · buildNumber · result · log URL 등)
200JobAck { job_id, event_type, status: 'queued' }
03

Agent 재실행

webhook 과 동일한 페이로드로 운영자가 수동 재실행할 때 쓰는 엔드포인트입니다.

수동 / 재시도

agent
POST/agent/jenkins-build-completed202

Jenkins 완료 이벤트를 동일 페이로드로 재실행합니다. (source=manual 로 기록)

bodyJenkinsBuildEvent (webhook 과 동일)
200JobAck
04

Admin

관리 패널이 쓰는 런타임 설정 · 이력 API. 전체가 아키텍트 전용(require_admin)입니다.

Prompts — 노드별 프롬프트

/admin/prompts
GET/admin/prompts

프롬프트 목록 (활성 버전 + 히스토리).

200Envelope<PromptRead[]>
POST/admin/prompts201

새 프롬프트(버전) 생성.

200Envelope<PromptRead>
GET/admin/prompts/{prompt_id}

단일 프롬프트 조회.

200Envelope<PromptRead>
PATCH/admin/prompts/{prompt_id}

프롬프트 수정 / 활성 버전 전환.

200Envelope<PromptRead>

Channels — 메시지 채널

/admin/channels
GET/admin/channels

채널 설정 목록 (default: slack, 프로토타입은 stdout 폴백).

200Envelope<ChannelRead[]>
POST/admin/channels201

채널 추가.

200Envelope<ChannelRead>
PATCH/admin/channels/{channel_id}

채널 설정 수정.

200Envelope<ChannelRead>
DELETE/admin/channels/{channel_id}204

채널 삭제.

200(no content)

Integrations — 외부 자격 증명

/admin/integrations
GET/admin/integrations

Jenkins / SonarQube / LLM / Knowledge 자격 목록 (비밀은 마스킹).

200Envelope<IntegrationRead[]>
POST/admin/integrations201

자격 증명 등록 (비밀은 Fernet 으로 암호화 저장).

200Envelope<IntegrationRead>
PATCH/admin/integrations/{integration_id}

자격 증명 수정.

200Envelope<IntegrationRead>
DELETE/admin/integrations/{integration_id}204

자격 증명 삭제.

200(no content)

Jobs — 이력 · Spec · 재시도

/admin/jobs
GET/admin/jobs

작업 이력 목록. 담당자 필터 + 페이지네이션.

querylimit (1–200, 기본 50) · offset (≥0) · assignee_user_id
200Envelope<JobRead[]>
GET/admin/jobs/{job_id}

작업 상세 — 이벤트 페이로드 + steps[] 타임라인.

200Envelope<JobDetail>
GET/admin/jobs/{job_id}/spec

이 작업의 최신 생성 spec 조회 (없으면 404 spec_not_found).

200{ data: { job_id, spec, spec_guid, ... } }
POST/admin/jobs/{job_id}/spec

대시보드 'Spec 생성' — generate_dev_spec 노드를 실행해 markdown spec 을 합성하고 GUID 를 부여·저장합니다.

200{ data: { job_id, spec, spec_length, spec_guid } }
POST/admin/jobs/{job_id}/retry202

작업 재시도 — 원본 페이로드로 그래프를 다시 실행합니다.

200JobAck
05

Spec 외부 fetch

GUID 만 있으면 인증 없이 spec markdown 을 가져갈 수 있는 공개 엔드포인트. Dev Agent 연계용입니다.

공개 (no auth)

/specs
GET/specs/{guid}

GUID(feedback-XXXXXXXX) 로 spec 을 조회. 기본은 markdown 원문, format=json 이면 봉투 형태.

queryformat = md (기본, text/markdown) | json
200text/markdown · 또는 { data: { spec_guid, job_id, spec, ... } }
error400 invalid_guid · 404 spec_not_found