자동 리메디에이션 PR (npm)
리메디에이션 dry-run이 package.json 편집을 미리보기만 한다면, 자동 리메디에이션 PR은 짧은 수명의 GitHub App 설치 토큰을 사용해 프로젝트의 GitHub 저장소에 실제로 풀 리퀘스트를 생성합니다 — 브랜치, 커밋, PR까지.
외부 저장소에 대한 권한 있는 쓰기 작업이므로 옵트인이며 팀 관리자 전용입니다.
포털은 프로젝트에 명시적으로 연결하지 않은 저장소에는 절대 PR을 생성하지 않습니다. 대상 저장소는 프로젝트가 옵트인한 GitHub App 설치에서만 도출됩니다 — 호출자가 저장소를 지정할 수 있는 요청 필드는 없습니다. 프로젝트가 옵트인되어 있지 않으면 요청은 409로 거부됩니다.
사전 조건
- 팀 관리자가 팀에 대한 GitHub App 자격 증명을 등록합니다.
- 해당 자격 증명의 설치가
repository_full_name과 함께 프로젝트에 연결(옵트인)되어 있어야 합니다. 연결된 설치의 자격 증명이 폐기되지 않은 상태여야 합니다.
엔드포인트
POST /v1/projects/{project_id}/remediation/npm/pull-request
인증이 필요합니다(JWT 또는 API 키). 호출자는 프로젝트 팀의 팀 관리자여야 합니다. 볼 수 없는 프로젝트는 404(존재 은닉)를 반환합니다.
요청 본문 (선택)
| 필드 | 타입 | 설명 |
|---|---|---|
manifest | string | null | 편집할 package.json 원문. 생략하면 프로젝트의 최신 보존 스캔 소스에서 best-effort로 읽습니다. 대상 저장소는 본문에 포함되지 않습니다 — 옵트인에서 도출됩니다. |
응답
| 상태 | 의미 |
|---|---|
201 Created | 새 리메디에이션 PR이 생성되었습니다. 본문은 PR 레코드입니다. |
200 OK | 동일한 버전 변경 집합을 가진 기존 open PR이 반환되었습니다(멱등 — 중복 PR 없음). |
204 No Content | 리메디에이션할 항목이 없습니다(매니페스트가 이미 수정본을 충족). |
멱등성
각 시도는 버전 변경 집합(package → 대상 버전)으로 지문화됩니다. 동일한 지문을 가진 open PR이 이미 존재하면 두 번째 PR을 만들지 않고 그 PR을 반환합니다. failed 또는 superseded 레코드는 새 시도를 막지 않습니다.
PR에 담기는 내용
- 저장소 기본 브랜치에서 분기한 새 브랜치
trustedoss/remediation-<짧은-지문>. package.json만 편집하는 단일 커밋.- 버전 변경을 설명하는 풀 리퀘스트.
락파일은 편집하지 않습니다 — 병합 전에 npm install로 package-lock.json을 재생성하세요. PR 본문에 이 안내가 포함됩니다.
리메디에이션 PR 목록
GET /v1/projects/{project_id}/remediation/pull-requests
모든 팀 멤버가 프로젝트의 리메디에이션 PR 레코드를 최신순으로 조회할 수 있으며 page / page_size로 페이지네이션됩니다.
포털 UI에서 사용하기
API 없이 프로젝트의 보안 조치(Remediation) 탭(/projects/:id?tab=remediation)에서 동일한 흐름을 사용할 수 있습니다.
- 미리보기 — 미리보기 실행을 클릭하면 드라이런이 계산됩니다. 제안되는 버전 변경이
패키지 → 현재 → 권장표로 표시되며, 매니페스트 출처(업로드됨 / 보존된 스캔 소스 / 사용 불가)와 경고 — 특히 "package-lock.json을 재생성하려면npm install을 실행하세요" — 가 함께 표시됩니다. 변경 없음 결과와 매니페스트 없음 결과는 명시적인 빈 상태로 표시됩니다. - 보안 조치 PR 생성 — 팀 관리자에게만 표시됩니다. 클릭하면 PR이 생성되거나 (멱등적으로) 기존 PR이 반환되며, 결과는 새 탭에서 GitHub를 여는 링크로 표시됩니다.
- 프로젝트가 옵트인되어 있지 않으면(연결된 GitHub App 설치 없음) 버튼 대신 인라인 안내가 표시되어 실패하지 않습니다 — 팀 관리자가 먼저 저장소를 연결해야 합니다.
- 팀 관리자가 아닌 사용자에게는 버튼이 아닌 읽기 전용 안내가 표시됩니다.
- 보안 조치 풀 리퀘스트 — 아래 목록에는 프로젝트에 대해 생성된 모든 PR이 상태 배지(
creating/open/failed/superseded), 대상 저장소, 생성 시각과 함께 표시됩니다. 각 행은 GitHub의 PR로 연결됩니다.
상태 라이프사이클
| 상태 | 의미 |
|---|---|
creating | GitHub 쓰기 작업 시작 전에 레코드가 저장됨(중간 장애 시에도 흔적이 남음) |
open | GitHub가 생성된 PR을 반환함; pr_number / pr_url이 설정됨 |
failed | GitHub 쓰기 작업이 실패함; 시도가 기록됨 |
superseded | 향후 "새 PR이 이 PR을 대체" 흐름을 위한 예약 상태 |
오류
모든 오류는 RFC 7807 application/problem+json 형식입니다:
401— 인증 필요.403— 호출자가 프로젝트 멤버이지만 팀 관리자가 아님.404— 프로젝트를 찾을 수 없음 / 접근 불가.409— 프로젝트가 자동 리메디에이션 PR에 옵트인되어 있지 않음(저장소가 포함된 GitHub App 설치를 먼저 연결하세요).422— 매니페스트를 편집할 수 없거나, 저장된 저장소 식별자가 사용 불가.502— GitHub 쓰기 작업(브랜치 / 커밋 / PR) 실패. 오류는 GitHub HTTP 상태 코드만 보고합니다 — 토큰이나 응답 본문은 절대 포함하지 않습니다.