Codex로 GitLab 병합 요청 검토하기

Codex 코드 리뷰를 사용하면 GitLab 병합 요청에 대해 신호 대 잡음비가 높은 리뷰를 한 차례 더 받을 수 있습니다. Codex는 병합 요청 diff를 검토하고 저장소 지침을 따르며, 심각한 문제에 초점을 맞춘 표준 GitLab 코드 리뷰를 게시합니다.

GitLab 지원은 베타 버전이며 모든 ChatGPT 요금제에서 사용할 수 있습니다. Codex 통합은 Codex cloud에서 실행됩니다. Create pull request와 같은 데스크톱 앱의 GitHub 방식 저장소 제어 기능은 이 베타에 포함되지 않습니다.

시작하기 전에

다음 사항을 준비하세요.

• 연결된 GitLab 계정. GitLab.com에서는 표준 연결 절차가 필요하며, 자체 관리형 또는 Dedicated GitLab 인스턴스에서는 워크스페이스 관리자 템플릿 설정이 필요합니다.
• Codex가 저장소별 검토 지침을 따르게 하려면 AGENTS.md 파일.

Codex 코드 리뷰 설정하기

GitLab 연결 및 Codex 리뷰 ID 설정하기

GitLab.com에서는 ChatGPT에서 GitLab에 연결한 후 Codex에서 GitLab 계정을 연결하세요. 자체 관리형 또는 Dedicated GitLab의 경우 워크스페이스 관리자 템플릿이 게시된 후 각 검토자가 연결해야 합니다.

자체 관리형 또는 Dedicated GitLab에서는 Codex Cloud → Settings → Connectors를 여세요. 워크스페이스 관리자는 Codex에서 서비스 계정을 생성하도록 허용하거나 기존 서비스 계정의 개인 액세스 토큰을 저장할 수 있습니다.

Codex에서 계정을 생성하도록 허용하기

Codex Cloud → Settings → Connectors에서 자체 관리형 또는 Dedicated GitLab 호스트용 앱을 선택하고 → Set up service account → Create a service account를 선택하세요. 설정을 완료하는 워크스페이스 관리자에게는 GitLab 인스턴스 관리자 액세스 권한이 있어야 합니다. Selected groups 또는 Selected projects only를 선택한 다음, Codex가 작동할 위치를 선택하고 계정을 생성하세요. 그룹 옵션은 선택한 각 그룹에 Developer 액세스 권한을 부여하며, 이 권한은 해당 프로젝트와 하위 그룹에 상속됩니다. 프로젝트 옵션은 선택한 개별 프로젝트에만 Developer 액세스 권한을 부여합니다. Codex는 api 범위가 지정된 개인 액세스 토큰을 사용하는 ChatGPT Codex Connector 인스턴스 서비스 계정을 생성합니다.

기존 계정 사용하기

GitLab에서 서비스 계정을 생성하거나 선택하고, Codex가 작동할 그룹 또는 프로젝트에만 Developer 액세스 권한을 부여하세요. Service accounts 페이지에서 계정 → Manage access tokens → Add new token을 선택하여 만료일까지 30일 이상 남아 있고 api 범위가 지정된 개인 액세스 토큰을 생성하세요. Codex로 돌아가 Use an existing service account를 선택하고 토큰을 붙여 넣은 다음 Save token을 선택하세요. 토큰은 저장할 때 암호화되며 이후 다시 표시되지 않습니다.

서비스 계정 토큰 관리하기

워크스페이스 관리자는 Codex Cloud → Settings → Connectors에서 서비스 계정을 관리할 수 있습니다. Codex에서 생성한 계정의 경우 관리자가 현재 토큰을 취소하고 새 토큰을 생성할 수 있습니다. 기존 계정의 경우 관리자는 Codex에 저장된 토큰을 교체하거나 제거하고, 필요한 경우 GitLab에서 별도로 취소할 수 있습니다. 유효한 토큰이 구성될 때까지 Codex는 GitLab 활동에 응답할 수 없습니다.

GitLab 활동을 Codex에 전달할 방법 선택하기

코딩 작업 또는 프로젝트별 설정을 위한 프로젝트 환경 생성하기

Codex Cloud → Settings → Environments에서 GitLab 프로젝트를 선택하고, Codex가 해당 프로젝트의 코드를 작성하거나 실행하게 하려면 프로젝트 환경을 생성하세요. 예를 들어 파일 편집, 변경 사항 커밋, 병합 요청 브랜치에 업데이트 푸시 등의 작업이 해당합니다. 검토에 프로젝트별 비밀, 네트워크 액세스 또는 설정 명령이 필요한 경우에도 프로젝트 환경을 생성하세요.

GitLab.com에서는 Codex 검토를 활성화하려면 프로젝트 환경도 필요합니다.

환경을 생성하는 동안 Enable Codex activity from GitLab을 켜서 병합 요청, 댓글 및 이슈 이벤트를 Codex에 전달하는 프로젝트 웹훅을 설치하세요. 프로젝트 웹훅을 생성하려면 Maintainer 또는 Owner 액세스 권한, 관리자 액세스 권한, 또는 프로젝트 웹훅을 관리할 수 있는 사용자 지정 역할이 필요합니다. 서명된 프로젝트 및 그룹 웹훅에는 GitLab 19.0 이상이 필요합니다. 자체 관리형 GitLab 19.0에서는 webhook_signing_token 기능 플래그가 활성화되어 있는지 확인하세요. 이 플래그는 기본적으로 활성화되어 있으며 GitLab 19.1에서 제거되었습니다.

GitLab 그룹 전체 프로젝트에서 Codex 검토 활동 활성화하기

자체 관리형 또는 Dedicated GitLab에서 워크스페이스 관리자는 Environments → GitLab activity → Manage groups를 열어 그룹과 그 하위 그룹 전체에서 Codex 검토를 활성화할 수 있습니다. Codex는 해당 그룹 전체의 프로젝트를 포괄하는 그룹 웹훅을 설치합니다. 연결된 GitLab 사용자는 그룹 Owner여야 하며, 그룹 웹훅을 사용하려면 GitLab Premium 또는 Ultimate와 GitLab 19.0 이상이 필요합니다.

그룹 활동은 코드 리뷰를 활성화하지만 프로젝트 환경을 생성하지는 않습니다. 파일 편집, 명령 실행, 변경 사항 커밋 또는 병합 요청에 업데이트 푸시 등 GitLab에서 트리거되는 코딩 작업을 실행하려면 프로젝트 환경을 생성하세요.

코드 리뷰 정책 구성하기

Codex 리뷰 설정에서 코드 리뷰 정책을 구성하세요. 저장소 정책으로 Review my MRs, Review team MRs, Review all MRs 또는 Follow personal을 선택하세요. 그런 다음 리뷰 실행 시점으로 On MR open, On every push 또는 **Smart Trigger (Experimental)**를 선택하세요. 저장소 설정은 개인 기본값을 재정의할 수 있습니다.

Codex 검토 요청하기

1. 병합 요청 댓글에서 @codex review를 멘션하세요.
2. Codex가 반응(👀)하고 검토를 게시할 때까지 기다리세요.

Codex는 팀원처럼 병합 요청에 GitLab 토론과 메모를 게시합니다. 기본적으로 수동으로 요청한 리뷰에는 P0, P1 및 P2 발견 사항이 포함될 수 있으며, 자동 리뷰는 P0 및 P1 발견 사항에 중점을 둡니다.

자동 리뷰 활성화하기

조건을 충족하는 병합 요청을 자동으로 검토하려면 Codex 설정에서 Automatic reviews를 켜고 GitLab 저장소 정책과 트리거를 선택하세요. 트리거로는 On MR open, On every push 또는 **Smart Trigger (Experimental)**를 사용할 수 있습니다. 병합 요청 이벤트가 해당 정책 및 트리거와 일치하면 Codex는 @codex review 댓글 없이 실행됩니다.

프로젝트 웹훅 또는 상위 그룹 웹훅을 통해 GitLab 활동을 활성화해야 합니다. 자체 관리형 또는 Dedicated GitLab에서는 구성된 서비스 계정에도 프로젝트에 다시 쓸 수 있는 액세스 권한이 있어야 합니다. 구성된 프로젝트 환경이 있으면 Codex가 이를 사용합니다. 상위 그룹에서 이미 활동을 활성화했다면 하위 프로젝트가 해당 범위를 상속합니다.

Codex 검토 항목 사용자 지정하기

Codex는 저장소에서 AGENTS.md 파일을 검색하고 적용 가능한 코드 리뷰 규칙을 따릅니다. 규칙이 적용되는 코드와 가장 가까운 파일에 ## Code Review Rules 섹션을 추가하세요. 관련 검사를 그룹화하는 데 도움이 된다면 ### 제목을 사용하세요.

예를 들어 실험 보고 서비스에서는 노출 후 동작으로 인해 비교 코호트가 변경되지 않도록 할 수 있습니다.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

저장소 전체 규칙은 루트 AGENTS.md에, 서비스별 규칙은 services/experiment_reporting/AGENTS.md와 같은 중첩 파일에 배치하세요. Codex는 변경된 각 파일에 적용되는 루트 지침과 더 구체적인 지침을 함께 적용하므로, 관련 없는 변경 사항에 서비스별 컨텍스트를 포함할 필요가 없습니다.

검토자가 자주 설명하는 검사 내용을 담은 간결한 규칙 두세 개로 시작하세요. 유용한 규칙은 다음과 같습니다.

• 중대한 저장소별 동작에 집중하세요. 표시할 호환성 제약 조건, 데이터 경계 또는 안전하지 않은 부작용과 그것이 중요한 이유를 설명하세요.
• 안전한 경로나 예외를 명시하세요. Codex가 실제 문제와 예상된 동작을 구분할 수 있도록 충분한 컨텍스트를 제공하세요.
• 규칙의 범위를 명확히 하고 오래 유지될 수 있게 작성하세요. 변경될 수 있는 함수 이름보다 결과를 우선하고, 지침을 적용 대상 코드 가까이에 배치하세요.
• 기계적인 검사는 CI에 맡기세요. 서식, 린트 및 기타 결정론적 검사를 검토 규칙에서 제외하세요.

대표적인 병합 요청을 열고 @codex review를 사용해 리뷰를 요청하세요. 표시되는 발견 사항과 피드백을 바탕으로 규칙을 다듬고, 불필요한 알림을 만드는 지침의 범위를 좁히거나 제거하세요.

코드 리뷰 규칙은 Codex를 안내하지만 테스트, 브랜치 보호 또는 필수 승인을 대체하지는 않습니다.

일회성 검토 초점은 병합 요청 댓글에 추가하세요.

@codex review for issues in the database migration

리뷰 발견 사항 처리하기

리뷰 발견 사항을 수정하려면 구성된 프로젝트 환경이 필요합니다. 그룹 활동만으로는 리뷰를 지원할 수 있지만 코딩 작업은 실행할 수 없습니다. 프로젝트에 환경이 있다면 댓글을 하나 더 남겨 Codex에 동일한 병합 요청의 문제를 수정하도록 요청하세요.

@codex fix the P1 issue

Codex는 병합 요청을 컨텍스트로 사용하는 cloud chat을 시작하며, 권한이 있으면 수정 사항을 브랜치에 다시 푸시할 수 있습니다.

Codex에 다른 작업 요청하기

다른 코딩 작업에도 구성된 프로젝트 환경이 필요합니다. 그룹 활동만으로는 리뷰를 지원합니다. 댓글에서 review 이외의 내용과 함께 @codex를 멘션하면 Codex는 병합 요청을 컨텍스트로 사용하는 cloud chat을 시작합니다.

@codex fix the CI failures

코드 리뷰 문제 해결하기

Codex가 반응하지 않거나 검토를 게시하지 않는 경우 다음을 확인하세요.

• 의도한 GitLab 앱이 선택되었는지 확인하세요. 프로젝트별 설정을 사용하는 경우 프로젝트에 의도한 Codex cloud 환경이 있는지 확인하세요.
• 프로젝트 또는 상위 그룹의 활동이 활성화되었는지 확인하세요. GitLab에서 Webhooks → Recent events를 확인하고 병합 요청 및 메모 전달이 성공하는지 검증하세요.
• 자체 관리형 또는 Dedicated GitLab의 경우 프로젝트 또는 그룹 웹훅이 서명되어 있고 SSL 검증이 활성화되어 있으며 인스턴스가 GitLab 19.0 이상인지 확인하세요. 자체 관리형 GitLab 19.0에서는 webhook_signing_token 기능 플래그가 활성화되어 있는지 확인하세요. 실패 후 자동으로 비활성화된 훅은 복구하세요.
• 자체 관리형 또는 Dedicated GitLab의 경우 기존 서비스 계정의 개인 액세스 토큰이 활성 상태이고 api 범위가 있는지 확인하세요. Codex에서 서비스 계정을 생성했다면 Codex 커넥터 설정에서 올바르게 구성되어 있고 프로젝트 또는 그룹이 활성화되어 있는지 확인하세요.
• 자체 관리형 또는 Dedicated GitLab의 경우 연결된 GitLab 사용자뿐 아니라 워크스페이스 서비스 계정에도 프로젝트 또는 상위 그룹에 대한 Developer 액세스 권한이 있어 Codex가 검토와 반응을 게시할 수 있는지 확인하세요. 멤버십은 상속되지만 활동과 서비스 계정 액세스 권한은 별개입니다.
• Code review 또는 Automatic reviews가 활성화되어 있고 MR이 저장소 정책 및 트리거와 일치하는지 확인하세요.
• @codex review를 사용하세요.