자동 리메디에이션 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 상태 코드만 보고합니다 — 토큰이나 응답 본문은 절대 포함하지 않습니다.

사전 조건​

엔드포인트​

요청 본문 (선택)​

응답​

멱등성​

PR에 담기는 내용​

리메디에이션 PR 목록​

포털 UI에서 사용하기​

상태 라이프사이클​

오류​