GitHub Copilot 코드 리뷰 설정: 지침, 방화벽 및 러너(Runners)

빠른 답변

GitHub Copilot 코드 리뷰는 이제 풀 리퀘스트(Pull Request)의 **헤드 브랜치(head branch)**에서 리뷰 지침을 읽을 수 있으며, 전용 .github/workflows/copilot-code-review.yml 환경을 사용하고, Copilot 클라우드 에이전트(cloud agent)와 분리된 방화벽 및 러너(runner) 설정 뒤에서 실행될 수 있습니다.

작은 규모의 저장소(repository)라면 다음 네 가지 레이어로 시작하세요:

리뷰어가 무엇을 확인해야 합니까?
-> .github/copilot-instructions.md 또는 경로별 *.instructions.md

...

리뷰에 진정으로 프라이빗 인프라가 필요한 경우가 아니라면, GitHub 호스팅 러너(GitHub-hosted runners)와 기본 방화벽을 유지하십시오. Copilot은 승인(approval)이나 변경 요청(request for changes)이 아닌 **댓글(Comment)**을 남기므로, 결정론적인 CI와 사람의 승인이 여전히 머지 게이트(merge gate)로 남습니다.

대상 사용자

이 가이드는 GitHub에서 풀 리퀘스트를 리뷰하기 위해 Copilot을 사용하는 개인 개발자와 소규모 팀을 위한 것입니다. 이 가이드는 로컬 /security-review, CodeQL 또는 코드 스캐닝(code scanning)이 아닌, 호스팅된 PR 리뷰 환경에 초점을 맞춥니다. 어떤 보안 스캐너나 자동 수정(autofix) 단계를 사용할지에 대한 질문이 있다면 보안 리뷰 라우팅 가이드를 참조하십시오.

만약 여러 코딩 에이전트(coding agents) 전반에 걸쳐 AGENTS.md, CLAUDE.md 및 도구별 지침 파일 중 무엇을 선택할지의 문제라면, 교차 에이전트 지침 파일 가이드부터 시작하십시오. 여기서 더 좁은 범위의 작업은 Copilot의 풀 리퀘스트 리뷰를 재현 가능하고 제한된 범위 내로 만드는 것입니다.

2026년 7월 17일에 변경된 사항

GitHub는 네 가지 관련 변경 사항을 발표했습니다:

• Copilot 코드 리뷰 (code review)는 이제 Pull Request의 헤드 브랜치(head branch)로부터 copilot-instructions.md, 경로별 지침 파일(path-specific instruction files), 에이전트 기술(agent skills), 그리고 AGENTS.md를 읽습니다. 또한 REVIEW.md, GEMINI.md, CLAUDE.md도 인식합니다.
• 전용 .github/workflows/copilot-code-review.yml을 통해 리뷰 환경을 준비할 수 있습니다. 해당 파일이 없으면, copilot-setup-steps.yml 파일이 존재하는 경우 코드 리뷰는 해당 파일로 폴백(fallback)됩니다.
• 코드 리뷰를 위해 방화벽(firewall)이 기본적으로 활성화되어 있으며, 클라우드 에이전트(cloud agent)와는 독립적으로 구성할 수 있습니다.
• 조직(Organizations)은 코드 리뷰와 클라우드 에이전트에 대해 서로 다른 러너(runner) 유형을 선택할 수 있습니다.

헤드 브랜치 변경을 통해 까다로운 부트스트랩(bootstrap) 문제가 해결되었습니다. 즉, 기능 브랜치(feature branch)에서 새로운 리뷰 규칙을 도입하고 테스트한 뒤, 해당 규칙이 기본 브랜치(default branch)에 도달하게 할 수 있습니다. 이 가이드의 소스 확인 시점에는 일부 GitHub Docs 노트가 여전히 베이스 브랜치(base-branch) 동작을 설명하고 있었으나, 7월 17일자 변경 로그(changelog)는 헤드 브랜치 동작을 명시적으로 발표했습니다. 날짜가 명시된 제품 변경 사항을 최신으로 간주하되, 정책으로 신뢰하기 전에 브랜치 전용 테스트 규칙으로 이를 검증하십시오.

4가지 레이어 구성하기

1. 각 규칙을 가장 작은 유효한 파일에 배치하기

저장소 전역의 Copilot 리뷰 규칙에는 .github/copilot-instructions.md를 사용하십시오. 언어, 디렉토리 또는 서브시스템(subsystem) 규칙에는 applyTo 프론트매터(frontmatter)가 포함된 .github/instructions/*.instructions.md를 사용하십시오. AGENTS.md는 도구 전반에 걸쳐 적용되어야 하는 공유 사실 및 명령어를 위해 유지하십시오.

지원되는 모든 파일에 동일한 단락을 중복해서 작성하지 마십시오. 여러 파일을 함께 읽을 수 있으며, 충돌하는 규칙은 리뷰 동작을 진단하기 어렵게 만듭니다. 유용한 지침은 관찰 가능해야 합니다. 예: "결제 웹훅(payment webhook) 변경 시, 멱등성(idempotency)을 확인하고 관련 테스트를 지목하십시오." (O), "주의 깊게 리뷰하십시오." (X)

2. 필요한 경우에만 코드 리뷰에 별도의 환경 제공하기

클라우드 에이전트(cloud agent)와 코드 리뷰에 동일한 도구가 필요한 경우, 기존의 copilot-setup-steps.yml을 유지하십시오. 리뷰에 더 적은 의존성 세트(dependency set), 다른 러너(runner), 또는 더 엄격한 권한이 필요한 경우에는 copilot-code-review.yml을 생성하십시오.

보수적인 Node.js 시작점은 다음과 같습니다:

name: "Copilot Code Review Setup"

on:
...

GitHub의 환경(environment) 문서에 따르면 작업(job) 이름은 copilot-setup-steps여야 하며, 최소 권한(least-privilege) 원칙을 권장합니다. --ignore-scripts는 패키지 라이프사이클 스크립트(package lifecycle scripts)가 필요하지 않은 저장소에 대한 신중한 기본값입니다. 프로젝트에서 해당 스크립트가 필요하고 그 결과로 실행되는 내용이 허용 가능한 경우에만 npm ci로 교체하십시오.

설정(setup)의 성공 여부가 머지 게이트(merge gate)는 아닙니다. GitHub 문서에 따르면 설정 단계(setup step)가 실패하면 나머지 설정 단계는 중단되지만, 리뷰는 그 시점에 사용 가능한 환경을 가지고 계속 진행될 수 있습니다. 리뷰 세션 로그를 환경 품질의 증거로 취급하십시오.

3. 방화벽을 좁게 유지하기

권장되는 허용 목록(allowlist)은 일반적인 운영체제(operating-system) 저장소, 패키지 레지스트리(package registries), 인증 기관(certificate authorities), 그리고 브라우저 다운로드 호스트를 포함합니다. 리뷰 규칙이나 도구가 필요할 때만 도메인 또는 경로 범위 URL(path-scoped URL)을 추가하십시오.

경계(boundary)를 설정하는 것이 중요합니다. GitHub은 통합 방화벽(integrated firewall)이 에이전트가 Bash 도구를 통해 시작하는 프로세스는 보호하지만, MCP 서버나 설정 단계(setup steps)에서 시작된 프로세스는 보호하지 않는다고 명시합니다. 이는 유용한 제어 수단이지, 완전한 데이터 유출(exfiltration) 방어책은 아닙니다. 리뷰 지침이나 설정 파일에 프로덕션 자격 증명(production credentials)을 절대 배치하지 마십시오.

4. 편의성이 아닌 위험에 따라 러너를 선택하기

일반적인 저장소에는 표준 GitHub 호스팅 러너(GitHub-hosted runner)를 사용하십시오. 리뷰 컨텍스트 수집(context gathering)에 실제로 더 많은 CPU, 메모리 또는 디스크가 필요한 경우에만 더 큰 호스팅 러너를 사용하십시오. 7월 17일 발표에 따르면, 셀프 호스팅 러너(Self-hosted runners)는 내부 네트워크를 노출할 수 있으며 통합 코드 리뷰 방화벽을 지원하지 않습니다.

셀프 호스팅 러너(Self-hosted runner)를 피할 수 없는 경우, 이를 일회성(ephemeral) 및 단일 사용(single-use)으로 설정하고, GitHub의 통합 방화벽 외부에서 아웃바운드 네트워크 제어(outbound network controls)를 적용하며, 가능한 경우 읽기 전용 저장소 액세스(read-only repository access) 권한을 부여하고, 프로덕션 배포 자격 증명(production deployment credentials)을 러너에 두지 마십시오.

제어된 하나의 풀 리퀘스트(Pull Request)로 검증하기

모든 곳에 한꺼번에 자동 리뷰를 활성화하는 대신, 다음의 5단계 출시(rollout) 방식을 사용하십시오:

1. 웹훅(webhook) 코드 내 중복 전달 처리 확인과 같이, 실제 서브시스템(subsystem)에 대해 특정 브랜치 전용 지침(instruction)을 하나 추가합니다.
2. 해당 서브시스템을 변경하는 작은 풀 리퀘스트(pull request)를 생성하고 Copilot 리뷰를 수동으로 요청합니다.
3. 연결된 리뷰 세션(review session)을 조사합니다. 어떤 지침 파일(instruction files), 설정 단계(setup steps), 도구(tools), 네트워크 호출(network calls)이 사용되었는지 확인합니다.
4. 유용한 발견 사항, 오탐(false positives), 누락된 규칙, Actions 소요 시간(minutes), AI 크레딧(credits)을 기록합니다.
5. 리뷰 품질이 향상된 후에만 해당 규칙을 병합(merge)합니다. 그 후 해당 저장소에 대한 자동 리뷰를 고려하십시오.

풀 리퀘스트에 다음과 같이 간결한 증거 블록(evidence block)을 사용하십시오:

Copilot 코드 리뷰 증거
- 관찰된 지침 파일(Instruction files):
- 설정 워크플로 결과(Setup workflow result):
...

일반적인 실수

• 규칙을 변경된 서브시스템으로 한정하는 대신, 하나의 거대한 지침 파일을 작성하는 것.
• 리뷰 세션을 확인하지 않고 새로운 브랜치 규칙이 활성화되었다고 가정하는 것.
• copilot-code-review.yml이 필요하지 않은 쓰기 권한(write permissions)이나 비밀값(secrets)을 상속받도록 방치하는 것.
• 좁은 범위의 규칙을 추가하는 대신, 특정 패키지 호스트가 차단되었다는 이유로 방화벽을 비활성화하는 것.
• 프로덕션 시스템에도 접근 가능한 지속성(persistent) 셀프 호스팅 러너를 사용하는 것.
• Copilot의 코멘트를 승인(approval)으로 간주하거나, 테스트 및 사람의 리뷰를 AI 피드백으로 대체하는 것.

FAQ

copilot-code-review.yml을 즉시 생성해야 하나요?

아니요. 기본 환경이 프로젝트를 안정적으로 검사할 수 없거나, 코드 리뷰가 클라우드 에이전트(cloud agent)와 다른 환경을 필요로 할 때만 생성하십시오. 추가적인 설정은 Actions 시간, 네트워크 노출 면적(network surface), 그리고 유지 관리 비용을 증가시킵니다.

Copilot 코드 리뷰는 이제 head 브랜치 또는 base 브랜치의 지침(instructions)을 사용하나요?

GitHub의 2026년 7월 17일 변경 로그(changelog)에 따르면 head 브랜치를 사용합니다. 일부 문서 텍스트에는 여전히 base 브랜치라고 명시되어 있는 것을 확인했으므로, 이를 필수 제어 항목으로 만들기 전에 해가 없는 브랜치 전용 규칙(branch-only rule)과 리뷰 세션 로그(review session log)를 통해 검증하십시오.

코드 리뷰가 클라우드 에이전트(cloud agent)의 방화벽(firewall)과 러너(runner)를 공유해야 하나요?

요구 사항이 실제로 동일한 경우에만 그렇습니다. GitHub은 이제 별도의 설정을 노출하므로, 클라우드 에이전트가 더 넓은 빌드 환경(build environment)을 필요로 하더라도 코드 리뷰는 더 좁은 네트워크 액세스 권한을 가진 더 작은 호스팅 러너(hosted runner)에 머물 수 있습니다.

Copilot 코드 리뷰가 풀 리퀘스트(pull request)를 차단할 수 있나요?

아니요. GitHub 문서에 따르면 Copilot은 승인(Approve) 또는 변경 요청(Request changes) 대신 댓글 리뷰(Comment review)를 남깁니다. 병합 강제(merge enforcement)를 위해서는 필수 CI 체크(CI checks)와 사람의 승인을 사용하십시오.

출처

• GitHub Changelog: Copilot code review customization and configurability improvements: https://github.blog/changelog/2026-07-17-copilot-code-review-customization-and-configurability-improvements/

• GitHub Docs: Using GitHub Copilot code review: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review

• GitHub Docs: About GitHub Copilot code review: https://docs.github.com/en/copilot/concepts/agents/code-review

• GitHub Docs: Configure the development environment: https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment

• GitHub Docs: 방화벽 사용자 정의하기 (Customize the firewall): [https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-the-firewall]

• GitHub Docs: Copilot 코드 리뷰 지침 사용자 정의하기 (Customize Copilot code review instructions): [https://docs.github.com/en/copilot/tutorials/customize-code-review]