7 min read

GitHub Copilot 코드 리뷰를 저장소 규칙에 맞추는 방법: 지침, Setup, Firewall

2026년 7월 Copilot 코드 리뷰 변경을 기준으로 head 브랜치 지침, REVIEW.md, 전용 setup workflow, firewall과 runner를 실제 저장소 운영 규칙으로 구성하는 방법을 설명합니다.

GitHub Copilot Code Review GitHub Actions AI Agent Security

GitHub Copilot 코드 리뷰는 이제 단순히 PR diff를 읽는 기능이 아닙니다. 2026년 7월 17일 업데이트 이후에는 PR 브랜치의 지침을 시험하고, 리뷰 전용 환경을 만들고, 네트워크와 runner를 코드 작성 에이전트와 분리할 수 있습니다. 좋은 리뷰를 얻으려면 프롬프트를 길게 쓰는 대신 저장소 규칙, 실행 환경, 외부 접근 범위를 각각 관리해야 합니다.

GitHub의 7월 17일 공식 변경 사항에는 네 가지 핵심 변화가 포함됐습니다.

변화운영상 의미
custom instructions를 PR의 head 브랜치에서 읽음지침 변경 자체를 PR에서 시험할 수 있음
REVIEW.md, GEMINI.md, CLAUDE.md 지원기존 저장소 문서를 리뷰 컨텍스트로 재사용 가능
.github/workflows/copilot-code-review.yml 지원코드 작성 에이전트와 리뷰 환경을 분리 가능
전용 firewall과 runner 설정리뷰가 접근할 네트워크와 실행 자원을 별도로 제한 가능

핵심은 하나입니다. 리뷰 품질 문제를 모두 자연어 지침으로 해결하지 말고, 지침·환경·권한을 서로 다른 계층으로 분리해야 합니다.

먼저 어떤 파일에 무엇을 써야 하는지 구분합니다

Copilot 코드 리뷰가 읽을 수 있는 파일이 늘었지만, 모든 규칙을 하나의 CLAUDE.md에 넣는 것은 좋지 않습니다.

파일적합한 내용
.github/copilot-instructions.md저장소 전체에 적용되는 짧은 원칙
.github/instructions/**/*.instructions.md특정 경로·언어·기능에만 적용되는 규칙
AGENTS.md빌드, 테스트, 아키텍처, 작업 방식
REVIEW.mdPR 리뷰에서 반드시 확인할 항목
CLAUDE.md, GEMINI.md이미 운영 중인 모델·도구별 프로젝트 설명
.github/skills/*/SKILL.md반복 가능한 전문 검토 절차

Restato 저장소처럼 이미 CLAUDE.md와 콘텐츠 정책이 있다면, 프로젝트 설명을 다시 복제하기보다 리뷰 전용 규칙만 REVIEW.md로 분리하는 편이 낫습니다.

# REVIEW.md

## 반드시 막아야 하는 변경
- `npm run build`를 실패시키는 Astro·MDX 변경
- 실제 `src/content/config.ts` 스키마와 다른 frontmatter
- 존재하지 않는 내부 링크 또는 프로젝트 경로
- 브라우저 전용 API를 SSR 단계에서 직접 호출하는 코드
- 비밀키, 토큰, 개인 데이터가 포함된 변경

## 집중해서 볼 영역
- `src/content/blog/**`: title, description, date, tags와 MDX 문법
- `src/pages/**`: 정적 생성 경로와 canonical URL
- `.github/workflows/**`: 최소 권한과 Node 버전
- `src/components/tools/**`: 모바일 레이아웃과 오류 처리

## 리뷰 응답
- 심각도와 영향을 먼저 설명합니다.
- 수정 가능한 경우 최소 diff를 제안합니다.
- 취향 차이는 차단 이슈처럼 표현하지 않습니다.

이 문서는 사람 리뷰어도 읽을 수 있어야 합니다. AI 전용 암호 같은 표현보다 팀의 실제 리뷰 기준을 기록하는 편이 유지보수에 유리합니다.

head 브랜치 지침은 리뷰 규칙을 PR로 시험하게 해줍니다

이전에는 리뷰 지침을 기본 브랜치에 먼저 합쳐야 새 규칙을 적용해 볼 수 있었습니다. 7월 17일 공식 changelog는 Copilot 코드 리뷰가 copilot-instructions.md, *.instructions.md, agent skills, AGENTS.md를 PR의 head 브랜치에서 읽는다고 설명합니다.

이 변화로 다음 순서가 가능해집니다.

  1. 기능 브랜치에서 REVIEW.md나 path-specific instructions를 수정합니다.
  2. 같은 PR에 Copilot 리뷰를 요청합니다.
  3. 새 규칙이 과도한 경고를 만들거나 중요한 문제를 놓치는지 확인합니다.
  4. 규칙과 코드를 함께 수정합니다.
  5. 검증된 규칙만 기본 브랜치에 합칩니다.

다만 2026년 7월 21일 기준 일부 GitHub Docs 페이지에는 여전히 base 브랜치에서 지침을 읽는다는 이전 설명이 남아 있습니다. 새 동작을 사용할 때는 changelog 날짜를 기준으로 판단하고, 해당 PR의 review session logs에서 실제로 어떤 지침과 도구가 사용됐는지 확인하는 것이 안전합니다.

코드 리뷰 전용 setup workflow를 분리합니다

Copilot 코드 리뷰는 GitHub Actions 기반의 임시 환경에서 실행됩니다. 기본적으로 copilot-setup-steps.yml을 재사용하지만, 리뷰에 코드 작성 에이전트와 같은 도구·권한이 꼭 필요한 것은 아닙니다.

.github/workflows/copilot-code-review.yml을 만들면 리뷰 전용 환경을 구성할 수 있습니다. GitHub 문서의 setup workflow 규칙에 따라 job 이름은 copilot-setup-steps여야 합니다.

name: Copilot Code Review Setup

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-code-review.yml
  pull_request:
    paths:
      - .github/workflows/copilot-code-review.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm

      - name: Install dependencies
        run: npm ci

Restato의 현재 배포 환경과 일치시키기 위해 예시는 Node 20을 사용했습니다. 프로젝트가 Astro 6 이상으로 올라가면 이 값도 Node 22.12 이상으로 바꿔야 합니다. 마이그레이션 순서는 Astro 5에서 7.1로 올리기 전 점검할 것에서 정리했습니다.

setup 단계에는 리뷰에 실제로 필요한 것만 넣습니다.

  • 타입과 import를 확인해야 한다면 npm ci
  • 생성 코드가 있어야 정확히 리뷰할 수 있다면 코드 생성 명령
  • 특정 linter나 schema validator가 필요하다면 해당 도구 설치
  • private registry가 필요하면 최소 범위의 secret과 firewall 규칙

반대로 배포, 데이터 변경, 외부 서비스 쓰기 권한은 리뷰 환경에 넣지 않는 편이 좋습니다. 리뷰는 코드를 이해하는 작업이지 운영 환경을 복제하는 작업이 아닙니다.

setup 실패가 리뷰를 자동 중단시키지 않는 점을 주의합니다

GitHub의 개발 환경 문서에 따르면 setup step이 실패하면 남은 setup 단계를 건너뛰지만, Copilot은 현재 환경에서 작업을 계속할 수 있습니다. 따라서 npm ci가 실패했는데도 리뷰 결과가 생성될 수 있습니다.

이 동작은 다음 문제를 만들 수 있습니다.

  • 의존성이 없는 상태에서 import 오류를 놓침
  • generated type이 없어 잘못된 경고를 생성
  • 테스트 도구를 사용할 수 없어 diff만 보고 판단

그래서 setup workflow 성공 여부를 별도 required check로 취급하는 편이 안전합니다. Copilot 리뷰 댓글이 달렸다는 사실만으로 환경 준비가 정상적이었다고 판단하면 안 됩니다.

firewall은 기본 허용 목록보다 작업 목적부터 정합니다

Copilot 코드 리뷰는 기본적으로 firewall 뒤에서 실행됩니다. repository settings의 Copilot → Internet access에서 cloud agent와 code review의 규칙을 각각 설정할 수 있습니다.

먼저 리뷰가 외부 네트워크를 정말 필요로 하는지 판단합니다.

작업외부 접근 필요성
저장소 코드와 diff 검토대부분 불필요
공개 npm package metadata 확인registry 접근 필요 가능
사내 schema·문서 참조private endpoint allowlist 필요
외부 API 실제 호출리뷰 환경에서는 가급적 금지
Playwright로 공개 페이지 확인대상 도메인만 제한적으로 허용

기본 원칙은 필요한 도메인만 allowlist하는 것입니다. firewall을 끄는 것보다 리뷰가 왜 네트워크를 필요로 하는지 setup과 instructions에 명시하는 편이 낫습니다.

자체 호스팅 runner에서는 Copilot 코드 리뷰의 통합 firewall이 현재 지원되지 않습니다. 내부 네트워크에 접근할 수 있는 self-hosted runner를 사용한다면, GitHub 설정이 아니라 runner 네트워크 계층에서 egress와 내부 접근을 통제해야 합니다.

코드 작성 agent와 code review runner를 분리합니다

7월 17일 변경으로 조직 수준에서 Copilot cloud agent와 code review의 runner를 독립적으로 선택할 수 있습니다. 두 작업은 요구 자원이 다릅니다.

  • coding agent: 빌드, 테스트, 파일 수정, 긴 실행 시간이 필요할 수 있음
  • code review: diff 탐색과 정적 검토가 중심이며 쓰기 권한이 불필요

따라서 code review에 더 작은 runner를 쓰고, coding agent에만 큰 runner나 내부 리소스 접근을 허용할 수 있습니다. 비용보다 중요한 장점은 권한 경계입니다. 리뷰 agent가 배포 agent와 같은 네트워크와 secret을 사용할 이유가 줄어듭니다.

agent skills는 리뷰 용도로 이름과 범위를 좁힙니다

GitHub Docs는 Copilot 코드 리뷰가 repository의 agent skills와 MCP server를 사용할 수 있다고 설명합니다. 다만 모든 일반 작업 스킬이 리뷰에 적합한 것은 아닙니다.

.github/skills/
└── astro-content-review/
    └── SKILL.md
---
name: astro-content-review
description: Astro MDX와 콘텐츠 컬렉션 변경을 검토할 때 사용
---

# Astro Content Review

1. 실제 content schema를 먼저 읽습니다.
2. 새 MDX의 frontmatter 필드를 schema와 비교합니다.
3. slug와 내부 링크가 정적 경로로 생성되는지 확인합니다.
4. JSX로 해석될 수 있는 MDX 기호를 확인합니다.
5. 날짜, 제품 버전, 가격 주장은 공식 출처와 비교합니다.

스킬 이름과 description에 review 목적이 드러나야 Copilot이 관련 상황에서 사용할 가능성이 높아집니다. 게시·배포 스킬과 리뷰 스킬을 같은 디렉터리에 섞지 않는 편이 좋습니다.

실제 적용 순서

  1. REVIEW.md에 사람이 합의한 차단 기준을 작성합니다.
  2. .github/copilot-instructions.md에는 짧은 저장소 공통 규칙만 둡니다.
  3. path-specific instructions로 MDX, workflow, React 규칙을 분리합니다.
  4. copilot-code-review.yml에서 최소 의존성만 설치합니다.
  5. setup workflow 자체를 Actions 탭에서 먼저 검증합니다.
  6. firewall allowlist를 최소화합니다.
  7. 테스트 PR에서 지침 변경과 Copilot 리뷰를 함께 실행합니다.
  8. review session logs에서 사용한 지침, skill, MCP tool을 확인합니다.
  9. 반복되는 오탐은 instruction을 늘리기 전에 코드·schema·테스트로 해결합니다.

좋은 AI 코드 리뷰는 “더 똑똑한 모델”만으로 만들어지지 않습니다. 어떤 규칙을 읽고, 어떤 환경에서 검사하고, 어디까지 접근할 수 있는지를 저장소가 명확히 제공해야 합니다. 이번 업데이트의 가치는 Copilot 리뷰를 팀 규칙에 맞게 튜닝할 수 있다는 데 있지만, 더 중요한 변화는 그 설정을 PR과 GitHub Actions로 검증할 수 있게 됐다는 점입니다.