Codex로 GitLab 병합 요청 검토하기

Codex 코드 검토를 활용해 GitLab 병합 요청에 핵심 이슈를 짚는 추가 검토를 진행하세요. Codex는 병합 요청의 diff를 검토하고 레포지토리 지침을 따르며, 심각한 문제에 집중한 표준 GitLab 코드 검토 결과를 게시합니다.

GitLab 지원은 베타 기능이며 모든 ChatGPT 요금제에서 사용할 수 있습니다. Codex 연동은 Codex 클라우드에서 실행됩니다. 데스크톱 앱의 Pull Request 만들기 같은 GitHub 방식의 레포지토리 제어 기능은 이번 베타에 포함되지 않습니다.

시작하기 전에

다음 항목을 준비하세요:

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

Codex 코드 검토 설정

GitLab 연결 및 Codex 검토 계정 설정

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

자체 관리형 또는 Dedicated GitLab을 사용하는 경우 Codex Cloud → 설정 → 커넥터 메뉴를 여세요. 워크스페이스 관리자는 Codex가 서비스 계정을 만들도록 하거나 기존 서비스 계정의 개인 액세스 토큰을 저장할 수 있습니다.

Codex가 계정을 만들도록 설정

Codex Cloud → 설정 → 커넥터 메뉴에서 자체 관리형 또는 Dedicated GitLab 호스트에 사용할 앱을 선택한 다음 서비스 계정 설정 → 서비스 계정 만들기 순서로 선택하세요. 설정을 완료하는 워크스페이스 관리자는 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 기능 플래그가 활성화되어 있는지 확인하세요. 이 플래그는 기본적으로 활성화되어 있으며 GitLab 19.1에서 제거되었습니다.

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

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

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

코드 검토 정책 설정

코드 검토 정책은 Codex 검토 설정에서 설정하세요. 레포지토리 정책으로 Review my MRs, Review team MRs, Review all MRs, Follow personal 중 하나를 선택하세요. 그런 다음 검토 실행 시점으로 MR을 열 때, 푸시할 때마다, 스마트 트리거(실험 기능) 중 하나를 선택하세요. 레포지토리 설정이 개인 기본 설정에 우선 적용될 수 있습니다.

Codex 검토 요청

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

Codex는 팀원이 검토하듯 병합 요청에 GitLab 토론과 노트를 게시합니다. 기본적으로 수동으로 요청한 검토에는 P0, P1, P2 수준의 이슈가 포함될 수 있으며, 자동 검토는 P0 및 P1 수준의 이슈에 집중합니다.

자동 검토 활성화

조건에 맞는 병합 요청을 자동으로 검토하려면 Codex 설정에서 자동 검토 옵션을 켜고 GitLab 레포지토리 정책을 선택한 다음 트리거로 MR을 열 때, 푸시할 때마다, 스마트 트리거(실험 기능) 중 하나를 선택하세요. 병합 요청 이벤트가 해당 정책 및 트리거 조건과 일치하면 @codex review 댓글이 없어도 Codex가 실행됩니다.

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는 병합 요청을 컨텍스트로 사용하는 클라우드 채팅을 시작하며, 필요한 권한이 있으면 브랜치에 수정 사항을 푸시할 수 있습니다.

Codex에 다른 작업 맡기기

다른 코딩 작업에도 설정된 프로젝트 환경이 필요하며, 그룹 활동만으로는 검토만 수행할 수 있습니다. 댓글에서 @codex를 멘션한 후 review 이외의 내용을 입력하면 Codex가 클라우드 채팅을 시작하고 병합 요청을 컨텍스트로 사용합니다.

@codex fix the CI failures

코드 검토 문제 해결

Codex가 반응하지 않거나 검토 결과를 게시하지 않는 경우:

• 올바른 GitLab 앱이 선택되어 있는지 확인하세요. 프로젝트별 설정을 사용하는 경우에는 해당 프로젝트에 올바른 Codex 클라우드 환경이 설정되어 있는지도 확인하세요.
• 프로젝트 또는 상위 그룹에서 활동이 활성화되어 있는지 확인하세요. GitLab에서 웹훅 → 최근 이벤트 메뉴를 확인하고 병합 요청과 노트 이벤트가 정상적으로 전달되는지 확인하세요.
• 자체 관리형 또는 Dedicated GitLab에서는 프로젝트나 그룹 웹훅에 서명이 적용되어 있고 SSL 검증이 활성화되어 있으며 인스턴스가 GitLab 19.0 이상인지 확인하세요. 자체 관리형 GitLab 19.0에서는 webhook_signing_token 기능 플래그가 활성화되어 있는지 확인하고, 오류 발생 후 자동으로 비활성화된 훅은 복구하세요.
• 자체 관리형 또는 Dedicated GitLab에서는 기존 서비스 계정의 개인 액세스 토큰이 활성 상태이고 api 범위가 있는지 확인하세요. Codex가 서비스 계정을 만든 경우에는 해당 계정이 Codex 커넥터 설정에 올바르게 구성되어 있고 프로젝트 또는 그룹이 활성화되어 있는지 확인하세요.
• 자체 관리형 또는 Dedicated GitLab에서는 연결된 GitLab 사용자뿐 아니라 워크스페이스 서비스 계정에도 해당 프로젝트나 상위 그룹의 Developer 권한이 있는지 확인하세요. 그래야 Codex가 검토 결과와 반응을 게시할 수 있습니다. 멤버십은 상속되며, 활동 활성화와 서비스 계정 액세스 권한은 별개입니다.
• 코드 검토 또는 자동 검토 기능이 활성화되어 있고 MR이 레포지토리 정책 및 트리거 조건과 일치하는지 확인하세요.
• @codex review를 사용하세요.