Codex에서 GitHub 연동하기 ㅡ PR 자동 코드 리뷰부터 codex review 설정까지

이 글에서 사용하는 주요 용어 정의

용어정의

OpenAI Codex	코드베이스 문맥을 이해하고 코드 작성과 리뷰 작업을 보조하는 AI 시스템
Pull Request (PR)	작업 브랜치의 코드 변경 사항을 기준 브랜치에 병합하기 전 검토를 요청하는 절차
@codex review	GitHub PR 댓글에서 Codex 에이전트를 직접 호출해 코드 분석을 요청하는 멘션 명령어
AGENTS.md	AI 에이전트가 저장소 코드를 분석하고 리뷰할 때 준수해야 할 프로젝트 규칙 정의 파일

코드 리뷰는 소프트웨어 품질을 유지하는 핵심 단계이지만 리뷰어 일정에 따라 병목이 발생하기 쉽습니다. 일반적인 린터나 포맷터만으로는 런타임 결함이나 아키텍처 오류를 짚어내기 어렵습니다.

OpenAI Codex의 GitHub 연동 기능은 저장소 전체 구조와 diff를 함께 분석해 버그와 보안 이슈를 중심으로 피드백을 제공합니다. GitHub 연동 절차부터 @codex review 온디맨드 호출, 자동 리뷰 설정, AGENTS.md를 통한 팀 맞춤 규칙 주입 방법을 정리합니다.

1. GitHub 저장소 연동 절차

Codex가 PR을 분석하고 리뷰를 등록하려면 GitHub 계정 인증과 저장소 권한 설정이 필요합니다.

1. GitHub 계정 연결: Codex 웹 대시보드의 Settings 메뉴에서 Integrations 또는 Connected Accounts로 이동합니다. GitHub 연동을 선택하고 계정을 인증합니다.
2. 저장소 권한 부여: GitHub App 설치 화면에서 코드 리뷰를 적용할 저장소를 선택합니다. 전체 저장소(All repositories) 또는 특정 저장소(Only select repositories) 중 필요한 범위를 지정합니다.
3. 필수 권한 승인: Pull Request 읽기·쓰기 권한과 메타데이터 접근 권한을 확인하고 설치를 승인합니다.

권한 승인과 웹 설정에서 연동 상태가 활성화되면 해당 저장소 PR에서 기능을 호출할 수 있습니다.

2. 코드 리뷰 실행 모드: 온디맨드 vs 자동 리뷰

Codex 코드 리뷰는 팀 협업 방식에 따라 온디맨드 호출과 자동 실행 중 선택할 수 있습니다.

구분실행 방식적합한 환경

온디맨드 (@codex review)	PR 댓글에 명령어를 입력할 때만 분석 실행	초기 검증 단계, 호출량 조절, 특정 PR 선별 검토
자동 리뷰 (Automatic Review)	PR 생성 및 커밋 푸시 시 백그라운드 자동 실행	정기 코드 리뷰 자동화, 1차 상시 검증

온디맨드 리뷰 (@codex review)

저장소가 연동된 PR 댓글 창에 @codex review를 입력하면 Codex가 diff와 관련 코드를 분석하고 인라인 코멘트와 요약 리뷰를 남깁니다.

아래 명령어 구문은 공식 문서 규격을 바탕으로 구성한 예제이며 실제 저장소에서 실행 검증하지 않은 예제입니다.

• 기본 코드 리뷰: @codex review를 입력해 변경 사항의 결함과 잠재적 위험을 점검합니다.
• 보안 집중 점검: @codex security review를 입력해 취약점과 권한 문제를 집중 검토합니다.
• 범위 한정 점검: @codex review for issues in database migration처럼 특정 작업 범위로 분석을 좁힙니다.

PR 자동 리뷰 (Automatic Review)

모든 PR에 상시 1차 점검을 적용하려면 자동 리뷰를 활성화합니다. Codex 설정의 Code Review 메뉴에서 해당 저장소의 Automatic review를 켭니다.

설정을 켜두면 새 PR이 열리거나 새 커밋이 푸시될 때마다 Codex가 변경 사항을 감지해 자동으로 GitHub PR Review를 등록합니다.

3. AGENTS.md로 팀 맞춤형 리뷰 규칙 주입하기

Codex는 일반 코딩 관례뿐만 아니라 프로젝트 고유 컨벤션을 함께 고려할 때 유용한 피드백을 제공합니다. 저장소 루트에 AGENTS.md를 두면 Codex가 코드 리뷰 시 이 문서에 명시된 규칙을 분석 기준으로 참고합니다.

아래 설정은 실제 저장소에서 실행 검증하지 않은 예제입니다. 프로젝트 환경에 맞춰 필요한 규칙을 정의해 사용하세요.

# 프로젝트 개발 지침

## Code Review Rules
- **API 하위 호환성**: 기존 엔드포인트 변경 시 필드 삭제를 금지하고 신규 필드는 선택값으로 처리합니다.
- **에러 핸들링**: 외부 API 호출 구간에는 반드시 재시도 정책과 타임아웃 처리가 포함되어야 합니다.
- **테스트 커버리지**: 비즈니스 로직 함수를 추가할 때는 단위 테스트 코드가 동봉되어야 합니다.
- **스타일 피드백 배제**: linter가 처리하는 공백·줄바꿈 이슈는 지적하지 않고 런타임 결함에 집중합니다.

AGENTS.md를 설정해 두면 Codex는 코드 위반 사항을 지적할 때 해당 규칙을 인용해 피드백 근거를 제시합니다.

4. 실무 적용 시 고려사항

• 인간 리뷰어의 보조 도구: Codex는 P0/P1 버그와 런타임 예외 검토를 돕는 보조 도구입니다. 비즈니스 요구사항 부합 여부와 최종 병합 승인은 동료 리뷰어가 직접 판단해야 합니다.
• 계정 플랜별 호출 한도: 조직 계정 티어에 따라 호출 한도가 적용될 수 있습니다. 초기 도입 시에는 모든 PR에 자동 리뷰를 적용하기보다 @codex review 온디맨드 호출로 피드백 품질과 토큰 사용량을 선별 검증하는 방식을 권장합니다.
• CI 파이프라인 연계: 사내 CI/CD 파이프라인과 통합하려면 공식 GitHub Action인 openai/codex-action을 연계할 수 있습니다.

5. 마무리

Codex의 GitHub 연동은 코드 리뷰 과정에서 발생하는 단순 결함 점검 부담을 줄이고 개발팀이 핵심 설계 논의에 집중하도록 돕습니다.

초기에는 온디맨드 명령어인 @codex review로 피드백 품질을 검증한 뒤, 점진적으로 AGENTS.md 규칙을 다듬고 자동 리뷰를 활성화하는 방식을 권장합니다.

참고 링크

• OpenAI Codex 공식 개발자 문서
• Custom Code Review rules for Codex (OpenAI 공식)