주요 콘텐츠로 건너뛰기
AI 튜토리얼

RepoPilot으로 검증 중심의 GitHub 이슈 및 PR 수정 작업 실행하기

RepoPilot 설치, 신뢰할 수 있는 테스트와 저장소 정책 구성, 풀 리퀘스트 검토, 이슈 재현, Codex가 생성한 수정 사항 검증, 작업 관리 방법을 알아보세요. 또한 유지 관리자가 계속 제어하는 가운데 조건을 충족하는 수정 사항을 선택적으로 초안 풀 리퀘스트로 게시할 수 있습니다.

약 16분 소요
RepoPilot으로 검증 중심의 GitHub 이슈 및 PR 수정 작업 실행하기

RepoPilot의 기능

RepoPilot은 검증 중심의 소프트웨어 반복 작업을 위한 자체 호스팅 컨트롤러입니다. 선택한 GitHub Issues와 동일한 저장소의 풀 리퀘스트를 규칙 검토, 테스트 생성, 실패 재현, 코드 수정, 독립 검증, 그리고 선택적인 수정 브랜치 및 초안 풀 리퀘스트 게시를 포함하는 제한된 워크플로로 전환합니다.

이 프로젝트는 OpenAI Codex SDK를 사용해 저장소 규칙을 이해하고, 요구 사항 기반 테스트를 설계하며, 프로덕션 코드 변경을 제안합니다. 별도의 Docker 러너가 고정된 저장소 스냅샷을 대상으로 테스트를 실행합니다. 컨트롤러는 구성된 증거 및 정책 검사를 통과한 경우에만 결과를 게시합니다.

RepoPilot은 변경 사항을 자동으로 병합하거나 배포하지 않습니다. 유지 관리자가 작업을 선택하고 증거를 검토하며 최종 병합 결정을 내립니다.

제한된 워크플로 방식

  1. RepoPilot은 관련 base 및 head 커밋을 고정합니다.
  2. 적용 가능한 AGENTS.md 지침을 포함해 base 브랜치의 신뢰할 수 있는 정책을 불러옵니다.
  3. Codex가 변경 사항을 검토하고 테스트 또는 수정 후보를 제안합니다.
  4. 프로덕션 코드를 수정하기 전에 생성된 테스트를 고정합니다.
  5. 별도의 러너가 독립적인 스냅샷을 대상으로 테스트를 실행합니다.
  6. 컨트롤러가 안정적인 테스트 식별자, 실패 지문, 보호된 경로, 정책 결과 및 구성된 제한을 확인합니다.
  7. 조건을 충족한 결과는 별도 브랜치에 배치하고 사람의 검토를 위해 초안 풀 리퀘스트로 제출할 수 있습니다.

풀 리퀘스트의 경우 RepoPilot은 base와 head의 동작을 비교합니다. Issue의 경우 먼저 원본 기준선이 통과해야 하며, 이후 수정 사항을 제안하기 전에 새로 고정된 테스트로 보고된 결함을 재현하려고 시도합니다.

주요 기능 및 현재 범위

  • 고정된 입력: Base 및 head SHA, 제목과 본문 다이제스트, 최신성 검사 및 취소 기능을 통해 오래된 입력에 대한 검증을 방지합니다.
  • 신뢰할 수 있는 저장소 규칙: 정적 정책은 리터럴 검사와 JavaScript 또는 TypeScript 호출 규칙을 지원합니다. 중첩된 base 브랜치의 AGENTS.md 파일을 통해 의미 기반 검토를 안내할 수 있습니다.
  • 독립적인 테스트 실행: 컨트롤러는 모델의 평가를 신뢰하는 대신 별도의 Docker 러너에 실행을 위임합니다.
  • 다양한 테스트 생태계: 버전 1.3.0은 Node 테스트 러너, Vitest, pytest, Go 테스트 및 호환되는 JUnit XML 증거를 지원합니다.
  • 모노레포 지원: 구성에서 작업 디렉터리, 여러 개의 이름이 지정된 테스트 명령 및 일회용 종속 서비스를 사용할 수 있습니다.
  • 제한된 수정: 시도 횟수, 재시도, 모델 호출, 토큰, 작업 실행 및 전체 작업 시간을 제한할 수 있습니다.
  • 추적 가능한 보고서: 원자적 JSON 보고서와 축약된 Markdown 요약에 조사 결과, 테스트 결과, 패치, 시도 및 게시 상태가 보존됩니다.
  • 운영 복구: 작업 명령은 검사, 취소, 재개 및 재실행을 지원합니다. recover 흐름은 미리 보기와 검증된 정리를 통해 소유한 충돌 잔여물을 처리합니다.

현재 구현은 최대 10,000개 파일 또는 16MiB 규모의 공개 텍스트 기반 저장소를 대상으로 합니다. 포크 풀 리퀘스트 실행, 브라우저 종단 간 테스트, 호스팅 대시보드, 웹훅, 분산 큐, 자동 종속성 설치, 자동 병합 또는 배포는 제공하지 않습니다.

사전 요구 사항

Node.js를 설치하지 않으려는 경우 Linux, Windows 또는 macOS용 RepoPilot 1.3.0 포터블 릴리스를 다운로드할 수 있습니다. 소스에서 설치하려면 다음을 준비하세요.

  • Node.js 22, 권장 버전
  • npm 및 Git
  • Linux 컨테이너를 실행하도록 구성된 Docker
  • Codex 기반 검토, 테스트 계획 또는 수정 기능을 활성화할 때 필요한 OpenAI API 키
  • GitHub 액세스 또는 게시가 필요할 때 필요한 GitHub 토큰

컨트롤러와 Agent 이미지 버전은 1.3.0으로 일치시켜 사용하세요. 테스트 컨테이너는 기본적으로 네트워크에 액세스할 수 없으므로 Docker 이미지와 프로젝트 종속성을 미리 준비해야 합니다.

소스에서 RepoPilot 설치

1. 프로젝트 설치, 검증 및 빌드

복제한 RepoPilot 저장소에서 잠긴 종속성을 설치하고 프로젝트 검사와 테스트를 실행한 다음 컨트롤러를 빌드합니다.

npm ci
npm run check
npm test
npm run build

RepoPilot 자체의 개발 테스트는 모의 API, 에이전트, 러너 및 합성 픽스처를 사용합니다. 모델 크레딧을 소비하거나 Docker를 실행하거나 GitHub 콘텐츠를 작성하지 않습니다.

2. 로컬 구성 생성

제공된 예제 구성을 복사합니다.

cp repopilot.example.json config.local.json

PowerShell 사용자는 cp 대신 Copy-Item을 사용할 수 있습니다. config.local.json을 편집해 대상 저장소와 신뢰할 수 있는 테스트 명령을 지정하세요. 이 로컬 구성은 검토 중인 저장소 스냅샷 외부에 보관하세요.

예제 구성에서는 에이전트 검토, 수정 및 게시 기능이 비활성화되어 있습니다. 로컬 검증이 정상적으로 작동한 후에만 이러한 기능을 각각 활성화하세요.

3. Codex Agent 이미지 빌드

Codex 기반 의미 검토, 테스트 계획 또는 수정을 사용하려면 Agent 컨테이너를 빌드하세요.

docker build -f Dockerfile.agent -t repopilot-agent:local .

컨트롤러 환경에 OPENAI_API_KEY를 설정하세요. 이 키는 Agent 컨테이너에만 전달됩니다. 데스크톱 ChatGPT 자격 증명은 재사용되지 않습니다. GITHUB_TOKEN 또는 GH_TOKEN을 통해 제공된 GitHub 자격 증명은 컨트롤러에 남아 있습니다.

첫 번째 로컬 풀 리퀘스트 검사 실행

먼저 기본 브랜치와 기능 브랜치 간의 로컬 비교를 시작합니다:

npm run dev -- check --config config.local.json --repo /path/to/project --base main --head feature

/path/to/project, main, feature를 로컬 저장소와 참조로 바꾸세요. 로컬 check는 변경 사항을 게시하지 않으며 소스 체크아웃을 수정하지 않습니다.

RepoPilot이 생성된 테스트를 분류하는 방법

생성된 시나리오는 regression 또는 new_behavior로 분류됩니다. 기본값은 regression입니다.

  • 회귀 증거: 동일한 실행 테스트 케이스가 기본 리비전에서는 통과하고 헤드 리비전에서는 실패합니다.
  • 새 동작 증거: 해당 케이스가 기본 리비전에서는 실패하고 헤드 리비전에서는 통과하며, 제안된 테스트에 풀 리퀘스트 제목 또는 본문의 정확한 요구 사항 인용이 포함됩니다.
  • 검토 필요: 두 리비전 모두 실패하거나, 케이스가 건너뛰어졌거나 누락되었거나, 실행이 실패하거나, 테스트 검색 결과가 변경되거나, 기존 테스트 결과가 예기치 않게 변경된 경우입니다.

모델이 제공한 레이블은 실행기 증거를 재정의할 수 없습니다. 회귀가 자동 수정 대상이 되려면 동일한 실패 테스트 식별자와 지문으로 반복 확인되어야 합니다.

풀 리퀘스트를 지속적으로 검토하기

RepoPilot의 감시자는 초안이 아니면서 동일한 저장소에 있는 풀 리퀘스트를 폴링하고 자체 자동 수정 브랜치는 제외합니다. 구성을 검증하는 동안 폴링 주기를 한 번 실행하세요:

npm run dev -- watch --config config.local.json --once

결과를 확인한 후 감시자를 계속 실행하세요:

npm run dev -- watch --config config.local.json

게시 기능은 선택 사항이며 publish=true가 필요합니다. GitHub 토큰에는 저장소 Contents 및 Pull requests 쓰기 권한이 있어야 합니다. 게시하면 별도의 자동 수정 브랜치와 초안 풀 리퀘스트가 생성되며, 자동으로 강제 푸시하거나 병합하지 않습니다.

게시 전에 RepoPilot은 커밋 SHA와 풀 리퀘스트 설명을 다시 확인합니다. 기존 수정 브랜치 또는 풀 리퀘스트는 해당 브랜치의 부모와 트리가 검증된 결과와 일치하는 경우에만 재사용할 수 있습니다.

GitHub 이슈 재현 및 수정

이슈 수정은 유지 관리자가 명시적으로 선택해야 합니다. 이슈 123을 처리하려면 다음을 실행하세요:

npm run dev -- fix --issue 123 --config config.local.json

이슈 워크플로는 세 가지 주요 단계로 진행됩니다:

  1. 기준선 설정: 고정된 대상 리비전에서 기존 테스트가 통과해야 합니다.
  2. 버그 재현: RepoPilot은 이슈 설명에 연결된 테스트를 생성하고 고정합니다. 새 테스트는 보고된 실패를 재현해야 합니다.
  3. 수정 시도 및 검증: Codex가 코드 대체안을 제안하고, 독립 실행기가 고정된 생성 테스트, 기존 테스트 모음 및 저장소 정책을 확인합니다.

증거가 불충분하거나 불안정하거나 불완전하면 사람의 검토를 위해 워크플로가 중지됩니다. RepoPilot은 이슈를 자율적으로 선택하거나 제품 로드맵을 정의하거나 결과로 생성된 수정을 병합하지 않습니다.

신뢰할 수 있는 저장소 정책 추가

대상 기본 브랜치에 .repopilot/policy.json을 커밋하세요. 예를 들어 다음 규칙은 비활성화된 JavaScript 및 TypeScript 테스트를 거부합니다:

{
  "rules": [
    {
      "id": "no-disabled-tests",
      "kind": "forbid-call",
      "extensions": [".ts", ".js"],
      "callee": "test.skip",
      "message": "Keep regression tests enabled.",
      "severity": "error"
    }
  ],
  "exceptions": []
}

지원되는 정적 규칙 종류에는 forbiddenText, forbid-call, require-call이 있습니다. 호출 규칙은 직접 호출, 한정 호출 및 문자열 속성 액세스를 검사합니다. 별칭을 확인하거나 전체 프로그램 분석을 수행하지는 않습니다. 리터럴 규칙은 주석과도 일치할 수 있습니다.

정책 예외에는 ruleId, 정확한 경로, 사유, UTC 만료 타임스탬프 및 선택적 정확한 증거를 지정할 수 있습니다. 예외는 기본 정책에서 제공된 경우에만 신뢰되며, 만료된 예외는 발견 결과를 억제하지 않습니다.

필수 규칙과 금지 규칙이 겹치면 검토가 중지됩니다. 신뢰할 수 있는 규칙 파일을 수정하는 풀 리퀘스트는 유지 관리자 검토가 필요하며 자체 수정 작업을 승인할 수 없습니다.

테스트 증거를 신중하게 구성하기

기본 리포터는 node이며 node --test를 사용합니다. 신뢰할 수 있는 리포터를 사용할 수 있도록 먼저 RepoPilot을 빌드하세요. Vitest의 경우 reporter=vitest를 구성하고, 종속성이 고정된 신뢰할 수 있는 이미지에서 명시적인 vitest run 명령을 사용하세요.

  • 리포터 플래그는 신뢰할 수 없는 테스트 명령이 아니라 컨트롤러에 속합니다.
  • reporter=command는 출력만 수집하며 검증 또는 게시를 지원할 수 없습니다.
  • 실행기를 생략하면 정책만 검토되며 테스트는 not_run으로 기록됩니다.
  • 테스트가 0개이거나, 모든 테스트가 건너뛰어졌거나, 보고서 형식이 잘못되었거나, 테스트 식별자가 누락된 경우에는 통과로 간주되지 않습니다.
  • 구성된 종속 서비스는 폐기 가능한 내부 Docker 네트워크를 사용합니다.

기본 리비전에 존재하지 않는 내보내기를 포함하는 생성 테스트의 경우, 실행 중인 테스트 케이스 내부에서 해당 내보내기를 확인하세요. 구조화된 증거를 수집하기 전에 최상위 가져오기가 충돌하여서는 안 됩니다.

실행 중인 작업 및 완료된 작업 관리

RepoPilot은 .repopilot-data 아래에 보고서와 스냅샷을 저장합니다. 각 작업에는 JSON 증거와 Markdown 요약이 생성됩니다. 재시도된 실행은 TASK.execution-N.json과 같은 이름으로 이전 증거를 보관합니다.

작업 검사 및 취소

npm run dev -- tasks list --config config.local.json --status running --limit 20 --offset 0
npm run dev -- tasks show TASK_ID --config config.local.json --format markdown
npm run dev -- tasks cancel TASK_ID --config config.local.json

컨트롤러가 쓰기 잠금을 유지하는 동안에도 작업 목록 조회, 상세 조회 및 취소를 계속 사용할 수 있습니다. 취소는 검증 및 게시 중 확인되는 영구 요청을 생성합니다. 이미 완료된 GitHub 쓰기를 되돌릴 수는 없습니다.

작업 재개 또는 재실행

npm run dev -- tasks resume TASK_ID --config config.local.json
npm run dev -- tasks rerun TASK_ID --config config.local.json

resume은 작업 ID, 구성 및 제한을 유지합니다. 상태에 따라 검증을 다시 시작하거나 이미 검증된 작업의 게시를 계속합니다. rerun은 원래 고정된 커밋과 현재 구성을 사용하는 연결된 작업을 생성하며, 이전 보고서와 취소 표시를 유지합니다.

영구 상태이거나 종료되었거나 재시도 횟수를 소진한 작업은 재실행해야 합니다. 리플레이에는 기록된 로컬 저장소 또는 Git 캐시도 필요하며, 풀 리퀘스트 입력은 리플레이 중 다시 확인됩니다.

고급 운영 팁

보수적인 제한 사용

작업 시간 초과, maxCalls, maxAttempts, maxTaskExecutions 및 토큰 사용량에 상한이 있는 값을 구성하세요. maxTokens 값은 각 모델 호출 후 보고된 사용량을 기준으로 계산되므로 단일 호출이 이 값을 초과할 수 있습니다. 이를 엄격한 금전 지출 한도로 간주해서는 안 됩니다.

환경 장애를 별도로 처리

RepoPilot은 장애를 분류하고, 적합한 환경 문제에 단계별 제한 재시도를 적용합니다. 불안정한 테스트, 변경되는 탐색 결과 또는 불완전한 증거는 확인된 코드 결함으로 처리되지 않고 자동 수리를 차단합니다.

증거 체인 보호

수리 후보는 워크플로에 필요한 경우 생성된 테스트 ID를 유지하고 원래 베이스, 원래 헤드 및 생성된 테스트 케이스를 전달해야 합니다. 기존 테스트, 매니페스트, 구성, 정책 및 숨겨진 경로는 보호됩니다. 후보 수리 후 정적 및 의미 기반 정책 검사를 다시 실행합니다.

충돌 후 신중하게 복구

버전 1.3.0에는 중단된 작업이 소유한 리소스를 미리 확인하고 명시적으로 정리하는 recover 워크플로가 포함되어 있습니다. 오래된 잠금을 제거하기 전에 이전 프로세스가 중지되었는지 확인하세요. 레거시 잠금과 리소스는 수동 검사가 필요할 수 있습니다.

신뢰 경계 이해

컨트롤러, 보고서 및 러너는 사용자의 컴퓨터 또는 워커에서 실행되지만 Codex 모델 호출은 OpenAI 서비스를 사용하며 선택된 저장소 텍스트와 작업 컨텍스트를 전송합니다. RepoPilot을 자체 호스팅해도 오프라인 모델 추론이 제공되는 것은 아닙니다.

테스트 실행은 엔지니어링 증거를 제공하지만 악성 코드에 대한 변조 방지 증명을 제공하지는 않습니다. 심볼릭 링크, 서브모듈, 바이너리 및 대소문자 충돌 경로는 안전을 위해 처리를 중단합니다. 신뢰할 수 없는 저장소를 실행하기 전에 프로젝트의 보안 지침을 검토하세요.

결론

RepoPilot은 고정된 입력, 동결된 테스트, 독립적인 Docker 실행, 저장소 정책, 제한된 재시도 및 내구성 있는 증거를 Codex 지원 검토 및 수리와 결합합니다. 게시하지 않는 로컬 check로 시작하고, 리포터와 정책 구성을 검증한 다음, 증거가 팀의 기준을 충족할 때만 감시, Issue 수리 및 초안 풀 리퀘스트 게시를 추가하세요.