(주)이프 AI노하우 코드리뷰 두 번째 글입니다. 지난 글에서는 오르카(Orca)로 ChatGPT(Codex) 와 Claude(Claude Code) 에게 같은 과제를 시키고 서로 검증하게 하는 방법을 정리했습니다. 이번에는 그 전 단계, 오르카에 내 프로젝트와 GitHub 저장소를 연결하는 방법입니다.
이번에도 오르카를 직접 설치한 PC 에서 하나씩 해 보면서 화면을 남겼습니다. GitHub 예시는 누구나 받을 수 있는 공개 연습 저장소를 썼습니다.
먼저 알아 둘 두 단어 : 프로젝트와 워크트리
| 용어 | 뜻 |
|---|---|
| 프로젝트 | 오르카에 등록한 저장소(또는 폴더) 하나. 사이드바 맨 위에 이름이 보입니다 |
| 워크트리 | 그 저장소에서 갈라져 나온 독립 작업 폴더. 작업(브랜치) 하나마다 하나씩 만들고, 에이전트는 각자 자기 워크트리 안에서만 일합니다 |
즉 "프로젝트를 한 번 연결하고, 일을 시킬 때마다 워크트리를 하나씩 만든다" 가 오르카의 기본 흐름입니다.
방법 1 : 내 PC 에 있는 프로젝트 연결
사이드바의 프로젝트 추가를 누르면 아래 창이 뜹니다. 이미 PC 에 있는 프로젝트라면 폴더 찾아보기를 고르면 됩니다.
| 선택 | 이럴 때 |
|---|---|
| 폴더 찾아보기 | PC 에 있는 Git 저장소, 일반 폴더, 또는 저장소가 여러 개 들어 있는 상위 폴더를 한 번에 |
| URL 에서 복제 | GitHub 등 원격 저장소를 받아 오면서 바로 등록 |
| 새 프로젝트 만들기 | 빈 폴더에서 새로 시작 |
위쪽 호스트는 프로젝트가 실제로 놓일 컴퓨터입니다. 보통은 지금 쓰는 PC(Local Windows)이고, SSH 로 연결한 원격 서버를 고르면 그 서버의 저장소에서 에이전트를 돌릴 수도 있습니다.
명령줄을 선호하면 오르카에 함께 설치되는 CLI 로도 같은 일을 합니다.
orca repo add --path "D:\work\my-project"
방법 2 : GitHub 저장소를 URL 로 복제해 연결
프로젝트 추가 창에서 URL 에서 복제를 고르고, GitHub 저장소 주소와 받아 둘 상위 폴더를 넣은 뒤 클론을 누릅니다.
복제가 끝나면 사이드바에 GitHub 아이콘과 함께 프로젝트가 생깁니다. 이때 왼쪽 아래에 설정 스크립트 추가 안내가 뜨는데, 이게 꽤 중요합니다(아래 '처음 연결할 때 꼭 볼 설정' 에서 설명합니다).
"Destination already exists" 오류가 날 때
저희가 실제로 겪은 오류입니다. 받아 둘 위치에 같은 이름의 폴더가 이미 있으면 "Destination already exists and is not empty" 가 뜨며 복제가 멈춥니다. 이미 받아 둔 저장소라면 복제하지 말고 방법 1(폴더 찾아보기) 로 그 폴더를 연결하면 됩니다. 상위 폴더를 바꿔서 새로 받는 것도 방법입니다.
비공개(private) 저장소라면
공개 저장소는 주소만으로 받아지지만, 회사 저장소처럼 비공개라면 PC 의 Git 에 GitHub 인증이 되어 있어야 합니다. 아래 방법 3 의 GitHub CLI 로그인을 먼저 해 두면 복제와 이슈 · PR 연동이 한 번에 해결됩니다.
방법 3 : GitHub 이슈 · PR 까지 연결
저장소를 받아 오는 것과, 이슈 · PR · 검사(Checks) 상태를 오르카 안에서 보는 것은 별개입니다. 후자는 설정 → 연동에서 켭니다. GitHub 은 공식 명령줄 도구인 GitHub CLI(gh) 를 통해 연결되는데, 설치만 되어 있고 로그인이 안 되어 있으면 아래처럼 "인증되지 않음" 이 표시되고 할 일을 그대로 알려 줍니다.
gh auth login
터미널에서 위 명령을 실행해 브라우저로 GitHub 로그인을 마친 뒤, 연동 화면의 Re-check 를 누르면 연결됩니다. 로그인은 반드시 본인이 직접 하세요. 계정 정보는 PC 의 GitHub CLI 가 보관하고, 오르카는 그것을 빌려 씁니다.
연결되면 오르카 공식 문서 기준으로 다음이 됩니다.
- 워크트리가 해당 PR 과 연결되고, 사이드바에 PR 상태(열림 · 병합 · 닫힘)가 표시됩니다
- GitHub Actions 검사가 실패하면 워크트리에 빨간 표시가 붙고, 실패 로그를 안에서 열어 볼 수 있습니다
- 이슈를 골라 그 이슈에서 바로 워크트리를 만들 수 있습니다. 작업 이름이 채워지고 이슈가 연결된 채로 시작합니다
이슈 목록을 작업판에 띄우려면 설정 → 작업 소스에서 GitHub 을 표시로 둡니다. 같은 화면에서 GitLab, Linear, Jira 도 연결할 수 있어서, 팀이 어떤 이슈 관리 도구를 쓰든 "이슈 → 워크트리 → 에이전트" 흐름을 만들 수 있습니다.
명령줄로 이슈 번호를 붙여 워크트리를 만들 수도 있습니다.
orca worktree create --repo path:"D:\work\my-project" --name fix-login --issue 42 --agent claude --prompt "이슈 42 를 재현하고 고쳐 주세요"
처음 연결할 때 꼭 볼 설정 세 가지
1. 에이전트 권한 : 실제 업무 저장소라면 "수동"
오르카 첫 실행 화면에는 "Yolo / 권한 확인 위험하게 건너뛰기" 가 기본으로 켜져 있습니다. 켜 두면 에이전트가 명령을 실행할 때마다 묻지 않고 바로 실행합니다. 연습용 저장소에서는 편하지만, 실제 사업 코드나 장비와 연결된 PC 라면 설정 → 에이전트 → Agent 권한을 수동으로 바꾸는 것을 권합니다. 같은 화면에서 기본 에이전트와 실행 환경(Windows / WSL)도 고릅니다.
2. 설정 스크립트 : 새 워크트리에는 .env 와 패키지가 없습니다
워크트리는 Git 이 관리하는 파일만 가지고 갈라져 나옵니다. 그래서 .env 같은 비밀 설정 파일이나 설치된 패키지 폴더는 새 워크트리에 없습니다. 에이전트가 "빌드가 안 된다" 며 헤매는 원인의 대부분이 이것입니다. 복제 직후 뜨는 설정 스크립트 추가에 패키지 설치와 설정 파일 복사 명령을 넣어 두면, 워크트리를 만들 때마다 자동으로 실행됩니다.
3. 윈도우 터미널 셸
윈도우에서 npm 으로 설치한 Codex 는 PowerShell 실행 정책에 막혀 바로 꺼질 수 있습니다. 이 경우 Codex 를 명령 프롬프트나 Git Bash 셸로 실행하도록 설정하면 해결됩니다(지난 글에서 자세히 다뤘습니다).
정리 : 연결 체크리스트
| 순서 | 할 일 | 확인 |
|---|---|---|
| 1 | Claude Code · Codex 등 쓸 에이전트 설치와 로그인 | 오르카 첫 화면에 감지되는지 |
| 2 | 프로젝트 추가 : 내 폴더는 폴더 찾아보기, 원격은 URL 에서 복제 | 사이드바에 프로젝트가 보이는지 |
| 3 | gh auth login 후 설정 → 연동 → Re-check | GitHub 이 인증됨으로 바뀌는지 |
| 4 | 설정 → 작업 소스에서 GitHub(또는 Linear · Jira) 표시 | 작업 목록에 이슈가 뜨는지 |
| 5 | 설정 스크립트에 패키지 설치 · 설정 파일 복사 등록 | 새 워크트리에서 바로 빌드되는지 |
| 6 | 실제 업무 저장소는 Agent 권한을 수동으로 | 에이전트가 실행 전에 묻는지 |
여기까지 해 두면 이슈 하나를 골라 워크트리를 만들고, 두 에이전트에게 같은 과제를 맡겨 서로 검증하게 하는 지난 글의 흐름을 그대로 쓸 수 있습니다.
