GitHub Copilot CLI Remote — Repository가 필요한 이유와 전체 설정 절차

GitHub Copilot CLI를 로컬에서만 쓰다 보면 어느 순간 이런 화면을 만나게 된다 — *"This feature requires a repository."* 왜 이런 제약이 생겼는지, 그리고 Remote 모드를 제대로 활용하려면 무엇을 준비해야 하는지 정리한다.

## 1. Copilot CLI Remote란 무엇인가

기존 Copilot CLI는 터미널에서 로컬 코드베이스를 기반으로 질문하고 코드를 수정하는 방식이었다. **Remote(Agent) 모드**는 여기서 한 단계 더 나아간다.

- GitHub Issue를 Copilot에게 **직접 할당(assign)** 하면 클라우드에서 에이전트가 실행된다
- 에이전트는 **fork + branch 생성 → 코드 수정 → PR 제출**까지 자동으로 처리
- 개발자는 최종 PR만 리뷰하면 된다

> 💡 **핵심**: Copilot Remote는 "터미널 도우미"가 아닌 "비동기 코드 에이전트"다. 로컬 환경 없이도 GitHub 위에서 작업이 완결된다.

---

## 2. Repository가 필요한 이유

Copilot Remote는 단순한 API 호출이 아니라 **GitHub Actions 기반의 실행 환경**을 사용한다. 이 때문에 반드시 GitHub Repository가 있어야 한다.

| 구성 요소 | 역할 |
|-----------|------|
| `GitHub Repository` | 코드베이스 + Actions 실행 컨텍스트 |
| `GitHub Actions` | 에이전트 실행 환경 (runner) |
| `Copilot Workspace` | 에이전트가 읽는 파일 시스템 |
| `Pull Request` | 에이전트 작업 결과물 출력 |

로컬 폴더만 있고 `git remote`가 없는 상태에서는 에이전트가 **어디서 코드를 읽고, 어디에 결과를 쓸지** 알 수 없다. Repository URL이 곧 에이전트의 "작업 공간 주소"다.

> ⚠️ **Private repo도 가능**하다. Public 여부와 무관하게 Copilot이 설치된 org/개인 계정이면 동작한다.

---

## 3. 사전 조건 체크리스트

```
✅ GitHub Copilot 구독 (Individual 또는 Business/Enterprise)
✅ 대상 Repository가 GitHub에 존재 (remote 연결 필수)
✅ Copilot이 해당 Repository에 접근 권한 있음
✅ GitHub Actions가 활성화된 Repository
```

Personal 계정 기준으로 Settings → Copilot에서 활성화 여부를 확인할 수 있다.

---

## 4. 전체 설정 절차

### 4-1. Repository 생성 및 연결

```bash
# 기존 로컬 프로젝트를 GitHub에 연결
git init
git remote add origin https://github.com/username/repo-name.git
git push -u origin main
```

이미 remote가 연결된 프로젝트라면 이 단계는 건너뛴다.

### 4-2. Copilot CLI 설치 및 인증

```bash
# GitHub CLI 설치 (Copilot CLI는 gh extension 형태)
# Windows
winget install GitHub.cli

# extension 설치
gh extension install github/gh-copilot

# 인증
gh auth login
```

```bash
# 설치 확인
gh copilot --version
```

### 4-3. CLI에서 Repository 컨텍스트 연결

```bash
# 반드시 git repo 디렉터리 내에서 실행해야 함
cd my-project

# 일반 질문 (로컬 컨텍스트)
gh copilot suggest "Dockerfile 최적화"

# explain 모드
gh copilot explain "$(cat src/main.py)"
```

Copilot CLI는 현재 디렉터리의 `.git/config`에서 remote URL을 읽는다. **git repo가 아닌 디렉터리에서 실행하면 일부 기능이 비활성화된다.**

### 4-4. Remote Agent (Issue 할당) 사용

```bash
# GitHub Issue에 Copilot 할당
# UI: Issue 페이지 → Assignees → @Copilot 선택

# 또는 CLI로
gh issue create --title "Add unit tests for auth module" --assignee @Copilot
```

할당 후 Actions 탭에서 에이전트 실행 로그를 확인할 수 있다.

---

## 5. copilot-setup-steps.yml — 에이전트 환경 커스터마이징

에이전트가 실행되는 환경을 미리 정의할 수 있다. 프로젝트 루트에 `.github/copilot-setup-steps.yml`을 추가하면 된다.

```yaml
# .github/copilot-setup-steps.yml
steps:
  - name: Install dependencies
    run: npm ci

- name: Setup Python
    uses: actions/setup-python@v5
    with:
      python-version: '3.12'

- name: Install Python deps
    run: pip install -r requirements.txt
```

이 파일이 없으면 에이전트는 기본 환경(Node.js, Python 기본 버전 등)에서 실행된다. **의존성이 복잡한 프로젝트일수록 이 파일이 중요하다.**

---

## 6. 자주 마주치는 문제

| 증상 | 원인 | 해결 |
|------|------|------|
| `This feature requires a repository` | git remote 없음 | `git remote add origin` |
| 에이전트가 PR을 못 만듦 | Branch protection rule | 에이전트용 bypass 규칙 추가 |
| Actions 탭에 실행 없음 | Copilot 권한 미설정 | Settings → Copilot → Repository access |
| 로컬 파일 변경이 반영 안 됨 | Remote와 push 안 됨 | `git push` 후 재시도 |

> 💡 **핵심**: Copilot CLI Remote의 모든 기능은 "GitHub Repository = 에이전트의 작업 공간"이라는 전제 위에 설계됐다. Repository 연결이 첫 번째 단계인 이유다.

GitHub Copilot CLI Remote — Repository가 필요한 이유와 전체 설정 절차

// COMMENTS

ON THIS PAGE