코드 리뷰 플로는 에이전틱 AI로 코드 리뷰를 간소화하는 데 도움을 줍니다.

이 플로는 다음을 수행합니다.

• 코드 변경 사항을 분석합니다.
• 리포지터리 구조와 파일 간 의존성에 대한 향상된 컨텍스트 이해를 제공합니다.
• 실행 가능한 피드백이 있는 자세한 리뷰 댓글을 제공합니다.
• 프로젝트에 맞춘 사용자 정의 리뷰 지침을 지원합니다.

사전 요구 사항#

• GitLab Duo Agent Platform의 사전 요구 사항을 충족합니다.
• 최상위 그룹에 대해 Allow foundational flows 및 Code Review를 켭니다.
• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.
• 여러 GitLab Duo 네임스페이스에 속해 있는 경우 기본 GitLab Duo 네임스페이스를 설정합니다.
• gitlab--duo 태그와 Docker 이미지를 지원하는 executor로 자체 러너를 구성하거나 프로젝트에 대해 GitLab 호스팅 러너를 켭니다. 코드 리뷰 플로는 CI/CD 작업으로 실행되며 실행하려면 러너가 필요합니다.
• 권장 사항. 플로가 프로젝트의 툴체인과 의존성에 액세스할 수 있도록 에이전트 구성 파일을 생성합니다.

플로 사용#

코드 리뷰 플로는 GitLab UI와 REST API로 사용할 수 있습니다.

GitLab UI에서 리뷰 요청#

GitLab UI에서 리뷰를 요청하려면:

1. 왼쪽 사이드바에서 Code > Merge requests를 선택하고 머지 리퀘스트를 찾습니다.

2. 다음 방법 중 하나를 사용하여 리뷰를 요청합니다.

   • @GitLabDuo를 리뷰어로 할당합니다.
   • 댓글 상자에 빠른 작업 /assign_reviewer @GitLabDuo를 입력합니다.
   • 댓글 상자에서 @GitLabDuo를 멘션하고 리뷰를 요청합니다.
   • GitLab Duo 사이드바에서 새 에이전틱 채팅 대화 또는 기존 대화를 엽니다. 에이전틱 채팅에 머지 리퀘스트를 리뷰하도록 요청합니다.

3. 진행 상황을 모니터링하려면 왼쪽 사이드바에서 AI > Sessions를 선택합니다.

   에이전틱 채팅을 사용 중이라면 다음도 할 수 있습니다.

   • 채팅 대화에서 진행 상황을 확인합니다.
   • 대화에서 View Agent Session을 선택합니다.

REST API로 리뷰 요청#

REST API로 리뷰를 요청하려면 다음 파라미터로 플로를 트리거합니다.

• project_id를 머지 리퀘스트가 포함된 프로젝트로 설정합니다.
• goal을 리뷰할 머지 리퀘스트의 IID 또는 해당 머지 리퀘스트의 전체 URL로 설정합니다.
• workflow_definition을 code_review/v1로 설정합니다. 또는 ai_catalog_item_consumer_id를 코드 리뷰 플로의 소비자 ID로 설정합니다.
• 리뷰를 즉시 시작하려면 start_workflow를 true로 설정합니다.

다음 예시는 머지 리퀘스트 42의 코드 리뷰를 트리거합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "5",
    "goal": "42",
    "workflow_definition": "code_review/v1",
    "start_workflow": true
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

리뷰에서 GitLab Duo와 상호작용#

리뷰 후에는 댓글 상호작용에서 GitLab Duo와 피드백을 논의할 수 있습니다. 상호작용은 코드 리뷰 플로와는 별개의 기능입니다.

자세한 내용은 GitLab Duo와 상호작용을 참고합니다.

승인 및 변경 요청#

GitLab Duo는 리뷰 결과를 바탕으로 머지 리퀘스트를 승인하거나 변경을 요청할 수 있습니다.

GitLab Duo가 댓글을 남길 내용을 찾지 못하면 머지 리퀘스트를 승인합니다. 그렇지 않으면 변경을 요청합니다.

GitLab Duo의 승인은 필수 승인 수에 포함되지 않습니다.

변경 요청은 이후 리뷰에서 댓글을 남길 내용이 없어 승인되거나 사용자가 변경 요청을 우회할 때까지 머지 리퀘스트에 남아 있습니다. 변경 요청이 머지 리퀘스트의 머지를 차단하는 인스턴스에서는 GitLab Duo의 변경 요청도 같은 효과가 있습니다.

이 설정은 프로젝트, 그룹 또는 인스턴스에 대해 켤 수 있습니다.

후속 리뷰#

후속 리뷰를 시작하려면 GitLab Duo에 머지 리퀘스트를 다시 리뷰하도록 요청합니다. Start a new review on push가 켜져 있으면 새 변경 사항을 푸시할 때도 후속 리뷰가 시작됩니다.

GitLab Duo가 머지 리퀘스트를 다시 리뷰할 때는 이전 리뷰의 컨텍스트를 사용하여 새 변경 사항을 평가합니다.

이전 리뷰의 컨텍스트#

후속 리뷰는 다음 컨텍스트를 사용합니다.

• 이전 리뷰에서 GitLab Duo가 시작한 인라인 댓글 스레드. 모든 답글과 스레드의 해결 여부를 포함합니다.
• GitLab Duo가 인라인 리뷰 댓글을 남긴 가장 최근 커밋.

GitLab Duo는 전체 diff를 읽고 댓글을 남길 때 다음 규칙을 따릅니다.

• 마지막으로 댓글을 남긴 커밋 이후에 추가된 줄에 댓글을 남깁니다.
• 해당 커밋 이후에 추가된 줄이 없으면 diff의 어느 위치에든 댓글을 남깁니다.
• 버그, 보안 취약점, 데이터 손실과 같은 정확성 문제를 발견하면 diff의 어느 위치에든 댓글을 남깁니다.
• 이전 스레드가 이미 지적한 내용은 스레드가 해결되었더라도 반복하지 않습니다.

후속 리뷰는 사람이 시작한 스레드, 일반 머지 리퀘스트 댓글, 이전 요약 댓글을 사용하지 않습니다. GitLab Duo의 이전 인라인 댓글이 없으면 다음 리뷰는 전체 첫 리뷰로 진행됩니다.

후속 리뷰 활용#

GitLab Duo는 이전 스레드에 답글을 남기거나 스레드를 해결하지 않습니다.

후속 리뷰를 최대한 활용하려면:

• 스레드에 답글을 남겨 코드가 올바른 이유를 설명합니다. GitLab Duo는 설명을 받아들이고 해당 지적을 다시 제기하지 않습니다. 답글이 없으면 스레드가 해결되었더라도 GitLab Duo는 리뷰 요약에서 해당 지적을 미해결 사항으로 나열합니다.
• 수정 사항을 푸시하고 다음 리뷰에서 GitLab Duo가 검증하도록 합니다.
• GitLab Duo의 지적에 대한 논의는 해당 스레드에서 유지합니다. 후속 리뷰는 GitLab Duo 스레드 밖의 댓글을 읽지 않습니다.

컨텍스트 인식#

코드 리뷰 플로는 두 단계로 실행됩니다.

1. 사전 스캔: 플로가 머지 리퀘스트 diff를 검사하고 이를 사용하여 프로젝트 리포지터리에서 가져올 관련 컨텍스트를 식별합니다. 사전 스캔에는 보통 디렉터리 목록과 변경 사항이 참조하는 테스트 및 의존성과 같은 관련 파일의 내용이 포함됩니다. 실제로 가져오는 컨텍스트는 diff 분석 결과에 따라 달라집니다.

2. 리뷰: 플로가 대규모 언어 모델에 다음 데이터를 전달하여 리뷰를 실행합니다. 리뷰 단계에서는 필요할 때 추가 컨텍스트를 가져올 수 없습니다.

   • 사전 스캔 단계의 결과.
   • 머지 리퀘스트 제목.
   • 머지 리퀘스트 설명.
   • 머지 리퀘스트 diff.
   • 파일의 원본 버전.
   • 파일 이름.
   • 후속 리뷰에서는 답글을 포함한 이전 GitLab Duo 리뷰의 댓글 스레드.
   • 사용자 정의 리뷰 지침.

제외할 콘텐츠를 지정하려면 GitLab Duo에서 컨텍스트 제외를 참고합니다.

파일 및 컨텍스트 제한#

코드 리뷰 플로는 프롬프트를 실용적인 크기로 유지하기 위해 두 가지 제한을 적용합니다.

• 10,000줄보다 긴 파일의 경우 diff만 모델에 전송됩니다. 전체 파일 내용은 포함되지 않습니다.
• 사전 스캔에서 수집하는 총 컨텍스트는 약 1 MiB로 제한됩니다. 이 제한을 초과하면 리뷰 단계 실행 전에 컨텍스트가 약 800 KiB로 잘립니다.

이러한 제한은 플로가 수집하는 데이터에 적용되며 선택한 모델의 컨텍스트 창과는 별개입니다.

매우 큰 머지 리퀘스트의 경우 잘린 컨텍스트로 인해 리뷰가 누락될 수 있습니다. 위험을 줄이려면:

• 머지 리퀘스트를 더 작은 머지 리퀘스트로 분할합니다.
• 리뷰와 관련이 없는 파일의 컨텍스트를 제외합니다.
• 그룹 Owner 또는 인스턴스 관리자에게 GitLab.com 또는 GitLab Self-Managed 및 GitLab Dedicated에서 다른 모델을 선택하도록 요청합니다.

사용자 정의 코드 리뷰 지침#

mr-review-instructions.yaml 파일로 코드 리뷰 플로의 동작을 사용자 정의합니다.

리포지터리별 리뷰 지침으로 GitLab Duo를 안내할 수 있습니다.

• 보안, 성능, 유지 관리성과 같은 특정 코드 품질 측면에 집중합니다.
• 프로젝트 고유의 코딩 표준과 모범 사례를 적용합니다.
• 맞춤형 리뷰 기준으로 특정 파일 패턴을 대상으로 합니다.
• 특정 유형의 변경 사항에 대해 더 자세한 설명을 제공합니다.

코드 리뷰 플로는 AGENTS.md 및 SKILL.md 파일을 참조하지 않습니다.

사용자 정의 지침을 구성하려면 GitLab Duo 리뷰 지침 사용자 정의를 참고합니다.

자동 리뷰#

GitLab Duo의 자동 리뷰는 프로젝트 또는 그룹의 모든 머지 리퀘스트가 초기 리뷰를 받도록 보장합니다.

사용자가 머지 리퀘스트를 만들면 다음 경우를 제외하고 GitLab Duo가 이를 자동으로 리뷰합니다.

• 초안으로 표시된 경우. GitLab Duo가 머지 리퀘스트를 리뷰하도록 하려면 준비됨으로 표시합니다.
• 변경 사항이 없는 경우. GitLab Duo가 머지 리퀘스트를 리뷰하도록 하려면 변경 사항을 추가합니다.
• 설정한 제외 규칙 중 하나 이상과 일치하는 경우. GitLab Duo가 머지 리퀘스트를 리뷰하도록 하려면 수동으로 리뷰를 요청합니다.

다음 그룹에는 자동 리뷰가 기본적으로 켜져 있습니다.

• GitLab 19.1 이상에서 GitLab.com의 새로운 GitLab Duo 트라이얼을 사용하는 그룹.
• GitLab 19.5 이상에서 GitLab.com의 첫 GitLab Duo 애드온을 추가하는 그룹. 새 Premium 및 Ultimate 구독이 있는 그룹을 포함합니다.

자동 리뷰를 활성화한 후에는 특정 머지 리퀘스트를 제외하는 규칙을 지정할 수 있습니다.

자동 리뷰에 대한 크레딧 사용이 어떻게 귀속되는지에 대한 자세한 내용은 실행되는 코드 리뷰 기능 확인을 참고합니다.

푸시할 때 새 리뷰 시작#

사용자가 머지 리퀘스트의 소스 브랜치에 푸시할 때 다음 조건이 모두 참이면 GitLab Duo가 후속 리뷰를 시작합니다.

• 프로젝트에 대해 자동 리뷰가 켜져 있습니다.
• 머지 리퀘스트 작성자에게 GitLab Duo 코드 리뷰가 아니라 코드 리뷰 플로가 실행됩니다.
• 머지 리퀘스트가 열려 있고 초안이 아닙니다.
• GitLab Duo가 이미 머지 리퀘스트의 리뷰어입니다.
• 푸시로 diff가 변경됩니다.

내용 변경이 없는 리베이스와 같이 diff를 변경하지 않는 푸시는 새 리뷰를 시작하지 않습니다. 푸시가 발생할 때 GitLab Duo 리뷰가 진행 중이면 GitLab은 해당 리뷰를 중지하고 새 리뷰를 시작합니다.

Start a new review on push는 기본적으로 켜져 있습니다. 프로젝트 또는 그룹에 대해 끌 수 있습니다.

프로젝트에 대한 머지 리퀘스트 제외#

프로젝트에 대해 자동 리뷰가 켜져 있으면 GitLab Duo는 적격한 모든 머지 리퀘스트를 리뷰합니다. 특정 머지 리퀘스트를 제외하려면 .gitlab/duo/mr-review-automated-rules.yaml 파일에 제외 규칙을 정의합니다.

제외 규칙은 자동 리뷰만 막습니다. 제외된 머지 리퀘스트에 대해서도 언제든 수동으로 리뷰를 요청할 수 있습니다.

제외 규칙을 정의하려면:

1. 리포지터리 루트에 .gitlab/duo 디렉터리가 없다면 생성합니다.

2. .gitlab/duo 디렉터리에 mr-review-automated-rules.yaml이라는 파일을 생성합니다.

3. 다음 형식으로 제외 규칙을 추가합니다.

   exclude:
     target_branches:
       - <pattern>
     source_branches:
       - <pattern>
     authors:
       - <pattern>
   

   각 키는 선택 사항입니다. 머지 리퀘스트가 어느 범주의 패턴과든 일치하면 GitLab Duo는 자동 리뷰를 건너뜁니다.

   • target_branches: 머지 리퀘스트의 대상 브랜치 이름과 일치합니다.
   • source_branches: 머지 리퀘스트의 소스 브랜치 이름과 일치합니다.
   • authors: 머지 리퀘스트 작성자의 사용자 이름과 일치합니다.

   패턴은 와일드카드(glob) 매칭을 지원합니다. 예를 들어 dependabot/*는 dependabot/으로 시작하는 모든 소스 브랜치와 일치합니다.

   예를 들어 릴리스 브랜치를 대상으로 하거나 봇 계정이 만든 머지 리퀘스트의 자동 리뷰를 건너뛰려면:

   exclude:
     target_branches:
       - "release/*"
     authors:
       - "*-bot"
   

4. 파일을 리포지터리의 기본 브랜치에 커밋합니다.

GitLab Duo는 리포지터리의 기본 브랜치에서 제외 규칙을 읽습니다. 다른 브랜치의 규칙은 적용하지 않습니다.

그룹에 대한 머지 리퀘스트 제외#

그룹과 그 하위 그룹의 모든 프로젝트에 대한 제외 규칙을 정의하려면 템플릿으로 사용할 프로젝트를 지정합니다. 템플릿 프로젝트에는 .gitlab/duo/mr-review-automated-rules.yaml 파일이 있어야 합니다.

GitLab Duo는 그룹 템플릿 프로젝트의 제외 규칙을 개별 프로젝트에 정의된 규칙과 결합합니다. 두 수준에서 같은 범주가 정의되면 프로젝트의 규칙이 우선합니다. 그룹과 하위 그룹이 각각 템플릿 프로젝트를 설정하면 GitLab Duo는 모든 수준의 규칙을 결합합니다.

사전 요구 사항:

• 그룹에 대한 Owner 권한.
• 그룹의 프로젝트에 설정하려는 제외 규칙이 포함되어 있습니다.

그룹에 대한 제외 규칙을 구성하려면:

문제 해결#

코드 리뷰 플로를 사용할 때 문제가 발생할 수 있습니다.

이러한 문제를 해결하는 방법에 대한 자세한 내용은 문제 해결을 참고합니다.

관련 주제#

• 머지 리퀘스트의 GitLab Duo
• Agent Platform AI 모델
• GitLab Duo Enterprise 좌석에 대해 코드 리뷰 플로 켜기.