Codex 코드 리뷰를 사용하면 GitLab 병합 요청에서 중요한 문제를 한 번 더 점검할 수 있습니다. Codex는 병합 요청의 변경 사항을 리포지터리 지침에 따라 검토하고, 심각한 문제를 중심으로 표준 GitLab 코드 리뷰를 게시합니다.
GitLab 코드 리뷰 통합 기능은 베타 단계이며 모든 ChatGPT 요금제에서 사용할 수 있습니다. 이 기능은 Codex Cloud에서 실행됩니다. 이번 베타에는 pull request 만들기 등 데스크톱 앱에서 제공하는 GitHub 방식의 리포지터리 관리 기능은 포함되지 않습니다.
클라우드 환경을 만들 때 리포지터리 선택 목록에 GitLab이 표시되면 연결된 계정으로 접근할 수 있는 GitLab.com 프로젝트를 선택하세요. GitLab에서 작업이나 리뷰를 시작하려면 아래 안내에 따라 웹훅을 설정하세요.
시작하기 전에
다음 항목을 준비하세요.
- 연결된 GitLab 계정이 필요합니다. GitLab.com에서는 표준 연결 플로우를 따르세요. 자체 관리형 GitLab 또는 GitLab Dedicated 인스턴스에서는 워크스페이스 관리자가 템플릿을 설정해야 합니다.
- Codex가 리포지터리별 리뷰 지침을 따르도록 하려면
AGENTS.md파일을 준비하세요.
Codex 코드 리뷰 설정하기
GitLab 연결 및 Codex 리뷰용 계정 설정하기
GitLab.com을 사용한다면 ChatGPT에서 GitLab에 연결한 후 Codex에서도 GitLab 계정을 연결하세요. 자체 관리형 GitLab 또는 GitLab Dedicated를 사용한다면 워크스페이스 관리자 템플릿이 게시된 후 각 리뷰어가 계정을 연결해야 합니다.
자체 관리형 GitLab 또는 GitLab Dedicated의 경우 Codex Cloud → 설정 → 커넥터로 이동하세요. 워크스페이스 관리자는 Codex가 서비스 계정을 만들도록 하거나 기존 서비스 계정의 개인 액세스 토큰을 저장할 수 있습니다.
Codex가 서비스 계정을 만들도록 설정하기
Codex Cloud → 설정 → 커넥터에서 자체 관리형 GitLab 또는 GitLab Dedicated 호스트에 해당하는 앱을 선택한 후 서비스 계정 설정 → 서비스 계정 만들기 순서로 선택하세요. 설정을 진행하는 워크스페이스 관리자에게는 GitLab 인스턴스의 관리자 권한이 있어야 합니다. 선택한 그룹 또는 선택한 프로젝트만 중 하나를 고른 다음, Codex가 작업할 그룹이나 프로젝트를 선택하고 계정을 만드세요. 그룹을 선택하면 서비스 계정은 선택한 각 그룹에서 Developer 권한을 얻으며 해당 그룹의 프로젝트와 하위 그룹은 이 권한을 상속합니다. 프로젝트를 선택하면 서비스 계정은 선택한 개별 프로젝트에서만 Developer 권한을 얻습니다. Codex는 ChatGPT Codex Connector 인스턴스 서비스 계정을 만들고 api 범위의 개인 액세스 토큰을 발급합니다.
기존 계정 사용하기
GitLab에서 서비스 계정을 만들거나 기존 계정을 선택하고, Codex가 작업할 그룹이나 프로젝트에서만 해당 계정에 Developer 권한을 부여하세요. 서비스 계정 페이지에서 계정을 선택한 다음 액세스 토큰 관리 → 새 토큰 추가 순서로 선택해 개인 액세스 토큰을 만드세요. 범위는 api로 지정하고 만료일은 최소 30일 후로 설정하세요. Codex로 돌아가 기존 서비스 계정 사용을 선택하고 토큰을 붙여 넣은 다음 토큰 저장을 선택하세요. 토큰은 저장 시 암호화되며 이후에는 다시 표시되지 않습니다.
서비스 계정 토큰 관리하기
워크스페이스 관리자는 Codex Cloud → 설정 → 커넥터에서 서비스 계정을 관리할 수 있습니다. Codex가 만든 계정이라면 관리자가 현재 토큰을 폐기하고 새 토큰을 발급할 수 있습니다. 기존 계정이라면 Codex에 저장된 토큰을 교체하거나 삭제하고, 필요한 경우 GitLab에서 별도로 폐기할 수 있습니다. 유효한 토큰을 설정해야 Codex가 GitLab 활동에 응답할 수 있습니다.
GitLab 활동을 Codex에 전달하는 방법 선택하기
코딩 작업이나 프로젝트별 설정에 필요한 프로젝트 환경 만들기
Codex Cloud → 설정 → 환경에서 GitLab 프로젝트를 선택하고 프로젝트 환경을 만드세요. Codex가 해당 프로젝트에서 코드를 작성하거나 실행하려면 이 환경이 필요합니다. 예를 들어 파일을 편집하거나, 변경 사항을 커밋하거나, 병합 요청 브랜치에 업데이트를 푸시하는 경우가 해당합니다. 리뷰에 프로젝트별 시크릿, 네트워크 액세스 또는 설정 명령어가 필요한 경우에도 프로젝트 환경을 만드세요.
GitLab.com에서는 Codex 리뷰를 활성화할 때도 프로젝트 환경이 필요합니다.
환경을 만들 때 GitLab에서 Codex 활동 활성화를 켜세요. 그러면 병합 요청, 댓글, 이슈 이벤트를 Codex에 전달하는 프로젝트 웹훅이 설치됩니다. 프로젝트 웹훅을 만들려면 Maintainer 또는 Owner 권한, 관리자 권한, 프로젝트 웹훅을 관리할 수 있는 사용자 지정 역할 중 하나가 필요합니다. 서명된 프로젝트 및 그룹 웹훅을 사용하려면 GitLab 19.0 이상이 필요합니다. 자체 관리형 GitLab 19.0에서는 webhook_signing_token 기능 플래그가 켜져 있는지 확인하세요. 이 플래그는 19.0에서 기본적으로 켜져 있으며 GitLab 19.1에서 제거되었습니다.
GitLab 그룹 전체의 프로젝트에서 Codex 리뷰를 위한 활동 활성화하기
자체 관리형 GitLab 또는 GitLab Dedicated에서는 워크스페이스 관리자가 환경 → GitLab 활동 → 그룹 관리 메뉴를 열어 그룹과 하위 그룹 전체에 Codex 리뷰를 활성화할 수 있습니다. Codex는 해당 그룹의 모든 프로젝트를 대상으로 하는 그룹 웹훅을 설치합니다. 연결된 GitLab 사용자에게는 그룹 Owner 권한이 있어야 합니다. 그룹 웹훅을 사용하려면 GitLab Premium 또는 Ultimate 요금제와 GitLab 19.0 이상이 필요합니다.
그룹 활동을 활성화하면 코드 리뷰를 사용할 수 있지만 프로젝트 환경이 생성되지는 않습니다. GitLab에서 파일 편집, 명령어 실행, 변경 사항 커밋, 병합 요청에 업데이트 푸시 등의 코딩 작업을 시작하려면 프로젝트 환경을 만드세요.
코드 리뷰 정책 설정하기
Codex 리뷰 설정에서 코드 리뷰 정책을 설정하세요. 리포지터리를 선택한 후 자동 리뷰를 켜세요. 이 옵션은 코드 리뷰 아래에 있습니다. 리뷰 항목에서는 누구의 병합 요청을 리뷰할지 선택하고, 트리거 항목에서는 리뷰를 언제 실행할지 선택하세요. 리포지터리 설정이 개인 기본 설정보다 우선할 수 있습니다.
Codex 리뷰 요청하기
- 병합 요청 댓글에
@codex review를 입력하세요. - Codex가 👀 반응을 남기고 리뷰를 게시할 때까지 기다리세요.
Codex는 팀원과 마찬가지로 병합 요청에 GitLab 토론과 메모를 남깁니다. 기본적으로 직접 요청한 리뷰에는 P0, P1, P2 문제가 포함될 수 있으며, 자동 리뷰는 P0과 P1 문제에 집중합니다.
자동 리뷰 활성화하기
조건에 맞는 병합 요청을 자동으로 리뷰하려면 Codex 설정에서 자동 리뷰를 켜고 GitLab 리포지터리 정책을 선택하세요. 그런 다음 병합 요청을 열 때, 푸시할 때마다, 스마트 트리거(실험적) 중에서 트리거를 선택하세요. 병합 요청 이벤트가 정책과 트리거 조건에 맞으면 @codex review 댓글 없이도 Codex가 리뷰를 실행합니다.
프로젝트 웹훅이나 상위 그룹 웹훅을 통해 GitLab 활동을 활성화해야 합니다. 자체 관리형 GitLab 또는 GitLab Dedicated에서는 설정된 서비스 계정에 프로젝트 쓰기 권한도 있어야 합니다. 프로젝트 환경이 설정되어 있으면 Codex는 해당 환경을 사용합니다. 상위 그룹에서 이미 활동을 활성화했다면 하위 프로젝트에도 적용됩니다.
Codex 리뷰 기준 맞춤 설정하기
Codex는 리포지터리에서 AGENTS.md 파일을 찾아 해당 코드에 적용되는 리뷰 규칙을 따릅니다. 규칙을 적용할 코드와 가장 가까운 파일에 ## Code Review Rules 섹션을 추가하세요. 필요하면 ### 제목을 사용해 관련 점검 항목을 묶으세요.
예를 들어 실험 결과를 보고하는 서비스에서는 실험 노출 이후의 행동에 따라 비교 대상 코호트가 달라지지 않도록 다음 규칙을 둘 수 있습니다.
## Code Review Rules
### 실험 코호트
- 실험군을 비교할 때 전환이나 리텐션 등 실험 노출 이후의 행동을 기준으로 비교 대상을 걸러내지 마세요.
배정 또는 노출을 기준으로 코호트를 구성하고, 전환은 결과로 보고하세요.리포지터리 전체에 적용할 규칙은 루트의 AGENTS.md에 작성하고, 서비스별 규칙은 services/experiment_reporting/AGENTS.md처럼 하위 디렉터리에 있는 파일에 작성하세요. Codex는 변경된 각 파일에 루트 지침과 해당 파일에 적용되는 세부 지침을 함께 적용합니다. 따라서 서비스와 무관한 변경 사항에는 해당 서비스의 컨텍스트가 필요하지 않습니다.
먼저 리뷰어가 자주 설명하는 점검 사항을 간결한 규칙 두세 개로 정리하세요. 규칙을 작성할 때는 다음 사항을 고려하세요.
- 리포지터리 고유의 동작 중 영향이 큰 부분에 집중하세요. 어떤 호환성 제약, 데이터 경계 또는 위험한 사이드 이펙트를 지적해야 하는지와 그 이유를 설명하세요.
- 안전한 방법이나 예외를 명시하세요. Codex가 실제 문제와 의도한 동작을 구분할 수 있도록 충분한 컨텍스트를 제공하세요.
- 규칙의 적용 범위를 명확히 하고 오래 쓸 수 있게 작성하세요. 바뀔 수 있는 함수 이름보다 기대하는 결과를 기준으로 작성하고, 지침을 적용할 코드 가까이에 두세요.
- 기계적으로 판별할 수 있는 항목은 CI에서 검사하세요. 서식, 린트 등 결과가 일정한 검사는 리뷰 규칙에서 제외하세요.
대표적인 병합 요청을 열고 @codex review로 리뷰를 요청하세요. Codex가 찾아낸 문제와 피드백을 바탕으로 규칙을 다듬고, 불필요한 지적을 유발하는 지침은 적용 범위를 좁히거나 삭제하세요.
코드 리뷰 규칙은 Codex의 리뷰 기준이 됩니다. 테스트, 브랜치 보호 또는 필수 승인을 대신하지는 않습니다.
이번 리뷰에서만 집중할 부분이 있다면 병합 요청 댓글에 함께 적으세요.
@codex review 데이터베이스 마이그레이션에 문제가 있는지 확인해 줘
리뷰에서 발견된 문제 해결하기
리뷰에서 발견된 문제를 수정하려면 설정된 프로젝트 환경이 필요합니다. 그룹 활동만 활성화하면 리뷰는 가능하지만 코딩 작업은 실행할 수 없습니다. 프로젝트에 환경이 있다면 같은 병합 요청에 댓글을 하나 더 남겨 Codex에 수정을 요청하세요.
@codex P1 문제를 수정해 줘Codex는 병합 요청을 컨텍스트로 삼아 레거시 클라우드 채팅을 시작합니다. 푸시 권한이 있으면 해당 브랜치에 수정 사항을 푸시할 수 있습니다.
Codex에 다른 작업 요청하기
다른 코딩 작업에도 설정된 프로젝트 환경이 필요합니다. 그룹 활동만 활성화한 경우에는 리뷰만 가능합니다. 댓글에서 @codex를 멘션하면서 review 이외의 내용을 입력하면 Codex가 병합 요청을 컨텍스트로 삼아 레거시 클라우드 채팅을 시작합니다.
@codex CI 실패 원인을 찾아 수정해 줘코드 리뷰 문제 해결하기
Codex가 반응을 남기거나 리뷰를 게시하지 않으면 다음을 확인하세요.
- 사용할 GitLab 앱이 선택되어 있는지 확인하세요. 프로젝트별 설정을 사용한다면 프로젝트에 올바른 Codex 클라우드 환경이 설정되어 있는지도 확인하세요.
- 프로젝트 또는 상위 그룹에서 활동이 활성화되어 있는지 확인하세요. GitLab에서 웹훅 → 최근 이벤트로 이동해 병합 요청 및 메모 이벤트가 정상적으로 전달되는지 확인하세요.
- 자체 관리형 GitLab 또는 GitLab Dedicated에서는 프로젝트나 그룹 웹훅에 서명이 적용되어 있는지, SSL 검증이 켜져 있는지, 인스턴스 버전이 GitLab 19.0 이상인지 확인하세요. 자체 관리형 GitLab 19.0에서는
webhook_signing_token기능 플래그가 켜져 있는지 확인하세요. 전송 실패로 자동 비활성화된 웹훅은 복구하세요. - 자체 관리형 GitLab 또는 GitLab Dedicated에서 기존 서비스 계정을 사용한다면 개인 액세스 토큰이 활성 상태이고
api범위가 지정되어 있는지 확인하세요. Codex가 서비스 계정을 만들었다면 Codex 커넥터 설정에서 계정이 올바르게 설정되어 있는지, 프로젝트 또는 그룹에서 활동이 활성화되어 있는지 확인하세요. - 자체 관리형 GitLab 또는 GitLab Dedicated에서는 연결된 GitLab 사용자뿐 아니라 워크스페이스 서비스 계정에도 프로젝트 또는 상위 그룹의 Developer 권한이 있는지 확인하세요. 이 권한이 있어야 Codex가 리뷰와 반응을 게시할 수 있습니다. 그룹 멤버십은 상속되지만, 활동 활성화와 서비스 계정 권한은 별도로 관리됩니다.
- 코드 리뷰 또는 자동 리뷰가 켜져 있고 병합 요청이 리포지터리 정책과 트리거 조건에 맞는지 확인하세요.
@codex review를 사용하세요.