모델 정보

• GitLab Duo with self-hosted models에서는 사용할 수 없습니다.

히스토리

• GitLab 18.3에서 ai_flow_triggers라는 플래그와 함께 GitLab.com에 도입되었습니다. 기본값으로 활성화됩니다.
• GitLab 18.6에서 CLI 에이전트에서 이름이 변경되었습니다.
• GitLab 18.6에서 Claude Code Agent 및 Codex Agent가 GitLab Self-Managed 및 GitLab Dedicated에서 활성화되었습니다.
• GitLab 18.7에서 그룹에서 활성화 기능이 ai_catalog_agents라는 플래그와 함께 도입되었습니다. GitLab.com에서 활성화됩니다.
• GitLab 18.10에서 maintainer가 프로젝트 레벨에서 직접 활성화하는 기능이 ai_catalog_project_level_enablement라는 플래그와 함께 도입되었습니다. GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 기본값으로 활성화됩니다.
• GitLab 18.11에서 기능 플래그 ai_catalog_project_level_enablement 제거.
• GitLab 19.0에서 Merge request ready 트리거 이벤트 유형이 merge_request_ready_flow_trigger라는 플래그와 함께 도입되었습니다. 기본값으로 비활성화됩니다.

GitLab Duo 에이전트는 병렬로 작동하여 코드 생성, 결과 조사, 동시 작업 수행을 도와줍니다.

에이전트를 생성하고 외부 AI 모델 제공자와 통합하여 조직의 요구에 맞게 커스터마이즈할 수 있습니다. 그런 다음 프로젝트 이슈, 에픽, 또는 머지 리퀘스트에서 코멘트나 토론에 해당 외부 에이전트를 멘션하여 작업을 완수하도록 요청할 수 있습니다.

외부 에이전트는 다음을 수행합니다:

• 주변 컨텍스트와 저장소 코드를 읽고 분석합니다.
• 프로젝트 권한을 준수하고 감사 추적을 유지하면서 적절한 조치를 결정합니다.
• CI/CD 파이프라인을 실행하고 GitLab 내부에서 머지 준비 완료 변경 사항 또는 인라인 코멘트로 응답합니다.

사전 요구 사항#

• GitLab Duo Agent Platform의 사전 요구 사항을 충족합니다.
• 플로우 실행이 켜져 있어야 합니다.
• 외부 에이전트가 켜져 있어야 합니다.

보안 고려 사항#

외부 에이전트는 서드파티 AI 모델 제공자와 통합되며, GitLab 내장 에이전트 및 플로우와 다른 보안 특성을 가집니다. 외부 에이전트를 사용함으로써 다음 위험을 수용합니다:

• 프롬프트 인젝션 취약성: GitLab은 프롬프트 인젝션 위험을 낮추기 위해 서드파티 프롬프트 스캔을 구현합니다. 이 스캔은 외부 에이전트에서는 사용할 수 없습니다.
• 서드파티 제공자 의존성: 외부 AI 모델 제공자가 GitLab이 아닌 모든 보안 제어(프롬프트 스캔, 모니터링, 경고 포함)를 관리합니다.
• 네트워크 접근: 외부 에이전트는 서드파티 AI 제공자에 대한 네트워크 호출을 수행합니다. 이러한 제공자에게 전송된 데이터는 해당 제공자의 보안 정책 및 데이터 처리 관행을 따릅니다.
• 제한된 격리: 외부 에이전트는 GitLab 네이티브 에이전트와 플로우에 적용되는 것과 동일한 수준의 네트워크 격리 및 보안 제한이 없습니다.

조직에서 외부 에이전트를 활성화하기 전에 보안 요구 사항과 선택한 AI 모델 제공자가 제공하는 보안 문서를 검토하세요.

Duo Agent Platform의 보안 위협 및 완화에 대한 광범위한 개요는 Duo Agent Platform 보안 위협 문서를 참조하세요.

GitLab 관리형 외부 에이전트 빠른 시작#

히스토리

• GitLab 18.8에서 GitLab.com에 도입되었습니다.

GitLab에서 테스트되어 사용 가능한 통합은 다음과 같습니다:

• Claude Code
• OpenAI Codex
• Amazon Q
• Gemini

에이전트를 생성하고 외부 AI 모델 제공자와 통합하기 전에 GitLab Duo Agent Platform의 사전 요구 사항을 충족해야 합니다.

관리형 외부 에이전트는 GitLab 관리형 자격 증명을 사용할 수 있으며, 추가 에이전트 구성 없이 그룹에서 활성화할 수 있습니다.

관리형 에이전트를 활성화하고 사용하기 위한 필수 단계:

1. AI Catalog에서 에이전트에 접근합니다. 에이전트 이름으로 검색하거나 직접 URL을 사용합니다.

   GitLab 관리형 외부 에이전트는 GitLab 유지 관리 배지([tanuki-verified])를 표시합니다.

2. 에이전트를 활성화합니다.

3. 이슈, 에픽 또는 머지 리퀘스트에서 외부 에이전트를 사용합니다.

Claude Code 에이전트#

GitLab의 Claude Code 에이전트는 GitLab 관리형 자격 증명을 사용하며 추가 구성이 필요하지 않습니다. 이 에이전트는 GitLab.com에서만 사용할 수 있습니다.

Codex 에이전트#

GitLab의 Codex 에이전트는 GitLab 관리형 자격 증명을 사용하며 추가 구성이 필요하지 않습니다. 이 에이전트는 GitLab.com에서만 사용할 수 있습니다.

Amazon Q Developer 에이전트#

Amazon Q Developer 에이전트는 GitLab 관리형 자격 증명을 사용하지 않습니다. 이 에이전트를 사용하려면 자신의 자격 증명을 제공해야 합니다. 이 에이전트는 GitLab.com에서만 사용할 수 있습니다.

Amazon Q Developer 에이전트를 사용하려면:

• 프로젝트의 CI/CD 설정에 다음 환경 변수를 추가합니다:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION_NAME
  • AMAZON_Q_SIGV4

Gemini로 개발 에이전트#

Gemini로 개발 에이전트는 GitLab 관리형 자격 증명을 사용하지 않습니다. 이 에이전트를 사용하려면 자신의 자격 증명을 제공해야 합니다. 이 에이전트는 GitLab.com에서만 사용할 수 있습니다.

Gemini로 개발 에이전트를 사용하려면:

• 프로젝트의 CI/CD 설정에 다음 환경 변수를 추가합니다:

  • GOOGLE_CREDENTIALS - Google 자격 증명 JSON 파일의 위치를 추가합니다. 자세한 내용은 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 참조하세요.
  • GOOGLE_CLOUD_PROJECT
  • GOOGLE_CLOUD_LOCATION

GitLab 관리형 에이전트를 다른 인스턴스에 추가#

히스토리

• GitLab 18.8에서 실험으로 도입되었습니다.

관리자는 Claude 에이전트와 Codex 에이전트를 GitLab 인스턴스에 추가할 수 있습니다.

사전 요구 사항:

• 관리자여야 합니다.

인스턴스에 외부 에이전트를 추가하려면:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. GitLab Duo를 선택합니다.
3. GitLab 관리형 외부 에이전트 아래에서 AI Catalog에 추가를 선택합니다.

API를 사용하여 외부 에이전트를 추가할 수도 있습니다.

자격 증명 접근#

히스토리

• GitLab 18.4에서 도입되었습니다.

외부 에이전트는 AI Gateway를 통해 GitLab 관리형 자격 증명을 사용합니다.

GitLab 관리형 자격 증명을 사용할 때:

• 외부 에이전트 구성에 injectGatewayToken: true를 설정합니다.
• GitLab AI Gateway 프록시 엔드포인트를 사용하도록 외부 에이전트를 구성합니다.

injectGatewayToken이 true일 때 다음 환경 변수가 자동으로 주입됩니다:

• AI_FLOW_AI_GATEWAY_TOKEN: AI Gateway 인증 토큰
• AI_FLOW_AI_GATEWAY_HEADERS: API 요청을 위한 포맷된 헤더

GitLab 관리형 자격 증명은 Anthropic Claude와 OpenAI Codex에서만 사용할 수 있습니다.

지원되는 모델#

GitLab 관리형 자격 증명에 대해 다음 AI 모델이 지원됩니다:

Anthropic Claude:

• claude-3-haiku-20240307
• claude-haiku-4-5-20251001
• claude-sonnet-4-20250514
• claude-sonnet-4-5-20250929

OpenAI Codex:

• gpt-5
• gpt-5-codex

CI/CD 변수 구성#

프로젝트에 변수를 추가하여 GitLab이 서드파티 제공자에 연결하는 방법을 결정합니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할을 가지고 있어야 합니다.

프로젝트 설정에서 변수를 추가하거나 업데이트하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. Settings > CI/CD를 선택합니다.
3. Variables를 확장합니다.
4. Add variable을 선택하고 필드를 입력합니다:

   • Type: **Variable (default)**을 선택합니다.

   • Environments: **All (default)**을 선택합니다.

   • Visibility: 원하는 가시성을 선택합니다.

     API 키 및 개인 액세스 토큰 변수의 경우 Masked 또는 Masked and hidden을 선택합니다.

   • Protect variable 체크박스를 해제합니다.

   • Expand variable reference 체크박스를 해제합니다.

   • Description (optional): 변수 설명을 입력합니다.

   • Key: CI/CD 변수의 환경 변수 이름을 입력합니다(예: GITLAB_HOST).

   • Value: API 키, 개인 액세스 토큰 또는 호스트의 값을 입력합니다.

5. Add variable을 선택합니다.

자세한 내용은 프로젝트 설정에 CI/CD 변수를 추가하는 방법을 참조하세요.

외부 에이전트의 CI/CD 변수#

다음 CI/CD 변수를 사용할 수 있습니다:

에이전트 활성화#

이슈, 머지 리퀘스트 또는 토론에서 트리거하기 위해 에이전트를 활성화합니다.

프로젝트에서 에이전트를 활성화하면, 동시에 해당 프로젝트의 최상위 그룹에서도 활성화됩니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할을 가지고 있어야 합니다.

외부 에이전트가 그룹 및 프로젝트의 AI > Agents 페이지에 나타납니다. 최상위 그룹의 모든 프로젝트 멤버는 이제 자신의 프로젝트에서 에이전트를 활성화할 수 있습니다.

그룹에 서비스 계정이 생성됩니다. 계정 이름은 다음 명명 규칙을 따릅니다: ai-<agent>-<group>.

프로젝트에서 활성화#

최상위 그룹에 외부 에이전트가 이미 활성화된 경우, 해당 그룹의 프로젝트에서 활성화할 수 있습니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할을 가지고 있어야 합니다.
• 프로젝트의 최상위 그룹에 에이전트가 활성화되어 있어야 합니다.

프로젝트에서 외부 에이전트를 활성화하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. AI > Agents를 선택합니다.
3. 오른쪽 상단 모서리에서 Enable agent from group을 선택합니다.
4. 드롭다운 목록에서 활성화할 외부 에이전트를 선택합니다.
5. Add triggers에서 외부 에이전트를 트리거하는 이벤트 유형을 선택합니다:
   • Mention: 이슈 또는 머지 리퀘스트의 코멘트에서 서비스 계정 사용자가 멘션될 때.
   • Assign: 이슈 또는 머지 리퀘스트에 서비스 계정 사용자가 할당될 때.
   • Assign reviewer: 머지 리퀘스트에 서비스 계정 사용자가 리뷰어로 할당될 때.
   • Merge request ready: 드래프트 머지 리퀘스트가 검토 준비 완료로 표시될 때.
6. Enable을 선택합니다.

외부 에이전트가 프로젝트의 AI > Agents 목록에 나타납니다.

최상위 그룹의 서비스 계정이 프로젝트에 추가됩니다. 이 계정에는 Developer 역할이 할당됩니다.

외부 에이전트 사용#

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 역할을 가지고 있어야 합니다.
• AI Catalog에서 외부 에이전트를 생성한 경우, 에이전트가 프로젝트에서 활성화되어 있어야 합니다.
• 에이전트가 에이전트 생성 브랜치 ^duo/(fix|feature|refactor|docs/).*에 푸시할 수 있도록 허용하려면 브랜치 규칙을 생성해야 할 수 있습니다.
• GitLab Self-Managed 전용. AI Catalog에서 외부 에이전트를 생성한 경우, 에이전트가 프로젝트에서 활성화되어 있어야 합니다.

1. 프로젝트에서 이슈, 머지 리퀘스트 또는 에픽을 엽니다.

2. 서비스 계정 사용자를 멘션하거나, 할당하거나, 리뷰를 요청합니다. 예를 들어:

   @service-account-username Can you help analyze this code change?
   

3. 외부 에이전트가 작업을 완료하면 확인이 표시되고, 머지 준비 완료 변경 사항 또는 인라인 코멘트가 나타납니다.

커스텀 외부 에이전트 생성#

히스토리

• GitLab 18.6에서 ai_catalog_third_party_flows라는 플래그와 함께 도입되었습니다. GitLab.com에서 활성화됩니다.
• GitLab 18.8에서 GitLab Self-Managed 및 GitLab Dedicated에서 활성화되었습니다.
• GitLab 18.8에서 ai_catalog_create_third_party_flows라는 추가 플래그가 필요하도록 변경되었습니다. 기본값으로 비활성화됩니다.

GitLab Self-Managed에서 ai_catalog_create_third_party_flows 기능 플래그가 활성화된 경우, AI Catalog로 외부 에이전트를 생성하고 환경에서 실행되도록 구성할 수 있습니다.

권장 워크플로우는 다음과 같습니다:

1. AI Catalog에서 에이전트를 생성합니다.
2. 프로젝트에 에이전트를 활성화하고 에이전트를 호출하는 방법을 결정하는 트리거를 지정합니다.

이 경우 서비스 계정이 자동으로 생성됩니다. 에이전트가 실행될 때 사용자의 멤버십과 서비스 계정 멤버십의 조합을 사용합니다. 이 조합을 복합 ID라고 합니다.

원하는 경우 수동으로 외부 에이전트를 생성할 수 있습니다.

에이전트 가시성#

히스토리

• 비공개 에이전트를 볼 수 있는 역할이 GitLab 18.7에서 확장되었습니다.

커스텀 외부 에이전트를 생성할 때 관리할 프로젝트를 선택하고 에이전트를 공개 또는 비공개로 설정합니다.

공개 에이전트:

• 누구나 볼 수 있으며 사전 요구 사항을 충족하는 모든 프로젝트에서 활성화할 수 있습니다.

비공개 에이전트:

• Guest, Planner, Reporter, Developer, Maintainer 또는 Owner 역할을 가진 관리 프로젝트 멤버만 볼 수 있습니다.
• 관리 프로젝트 이외의 프로젝트에서는 활성화할 수 없습니다.

AI Catalog에서 에이전트 생성#

먼저 AI Catalog에서 외부 에이전트를 생성합니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 역할을 가지고 있어야 합니다.

외부 에이전트를 생성하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. AI > Agents를 선택합니다.
3. New agent를 선택합니다.
4. Basic information 아래:
   1. Display name에 이름을 입력합니다.
   2. Description에 설명을 입력합니다.
5. Visibility & access 아래에서 Visibility에 Private 또는 Public을 선택합니다.
6. Configuration 아래:
   1. External을 선택합니다.
   2. 외부 에이전트 구성을 입력합니다. 자신의 YAML을 작성하거나 예제 구성을 편집할 수 있습니다.
7. Create agent를 선택합니다.

외부 에이전트가 AI Catalog에 나타납니다.

수동으로 외부 에이전트 생성#

UI 플로우를 따르지 않으려면 수동으로 외부 에이전트를 생성할 수 있습니다:

1. 프로젝트에 구성 파일을 생성합니다.
2. 서비스 계정을 생성합니다.
3. 에이전트를 호출하는 방법을 결정하는 트리거를 생성합니다.
4. 에이전트를 사용합니다.

이 경우 에이전트를 실행하는 데 사용되는 서비스 계정을 수동으로 생성합니다.

구성 파일 생성#

구성 파일을 수동으로 추가하여 외부 에이전트를 생성하는 경우, 각 외부 에이전트에 대해 다른 구성 파일을 생성해야 합니다.

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 역할을 가지고 있어야 합니다.

구성 파일을 생성하려면:

1. 프로젝트에 YAML 파일을 생성합니다. 예: .gitlab/duo/flows/claude.yaml
2. 구성 파일 예제 중 하나를 사용하여 파일을 채웁니다.

서비스 계정 생성#

외부 에이전트를 사용할 프로젝트에 대한 접근 권한이 있는 서비스 계정을 생성해야 합니다.

에이전트가 실행될 때 사용자의 멤버십과 서비스 계정 멤버십의 조합을 사용합니다. 이 조합을 복합 ID라고 합니다.

사전 요구 사항:

• GitLab Self-Managed에서는 다음 중 하나를 가지고 있어야 합니다:
  • 인스턴스에 대한 관리자 접근 권한.
  • 최상위 그룹에 대한 Owner 역할과 서비스 계정 생성 권한.

외부 에이전트를 멘션하는 각 프로젝트에는 고유한 그룹 서비스 계정이 있어야 합니다. 외부 에이전트에 작업을 할당할 때 서비스 계정 사용자 이름을 멘션합니다.

AI Catalog에서 외부 에이전트를 생성하고 최상위 그룹에서 활성화하면 ai-<agent>-<group> 이름으로 서비스 계정이 자동으로 생성됩니다. 예를 들어, GitLab Duo 그룹에서 Claude code agent라는 에이전트를 활성화하면 서비스 계정 이름은 ai-claude-code-agent-gitlab-duo입니다.

서비스 계정을 설정하려면 다음 작업을 수행합니다. 충분한 권한이 없으면 인스턴스 관리자 또는 최상위 그룹 Owner에게 도움을 요청하세요.

1. 최상위 그룹에 대해 서비스 계정을 생성합니다. 인스턴스에 대해 생성된 서비스 계정은 지원되지 않습니다.

   [!note] 기존 서비스 계정을 외부 에이전트로 구성할 때 해당 계정에 개인 액세스 토큰을 연결할 수 없습니다. 이 동작은 서비스 계정을 안전하게 유지하기 위한 것입니다.

2. 다음 스코프와 함께 서비스 계정에 대한 개인 액세스 토큰을 생성합니다:

   • write_repository
   • api
   • ai_features

3. Developer 역할로 서비스 계정을 프로젝트에 추가합니다. 이렇게 하면 서비스 계정에 최소한의 필요 권한이 부여됩니다.

프로젝트에 서비스 계정을 추가할 때 서비스 계정의 정확한 이름을 입력해야 합니다. 잘못된 이름을 입력하면 외부 에이전트가 작동하지 않습니다.

트리거 생성#

이제 외부 에이전트가 실행되는 시점을 결정하는 트리거를 생성해야 합니다.

예를 들어, 토론에서 서비스 계정을 멘션하거나 서비스 계정을 리뷰어로 할당할 때 에이전트가 트리거되도록 지정할 수 있습니다.

외부 에이전트 켜기/끄기#

히스토리

• GitLab 19.0에서 도입됨.

기본적으로 외부 에이전트는 켜져 있습니다. 최상위 그룹 또는 인스턴스에 대해 켜거나 끌 수 있습니다.

외부 에이전트가 꺼지면:

• 사용자가 외부 에이전트를 생성, 활성화, 비활성화, 수정 또는 실행할 수 없습니다. GitLab 관리형 외부 에이전트와 커스텀 외부 에이전트 모두 포함됩니다.

• 기존 외부 에이전트가 AI > Agents > Enabled 아래 프로젝트에 더 이상 표시되지 않습니다.

• 프로젝트에서 생성된 외부 에이전트는 AI > Agents > Managed 아래에 나타나지만 수정하거나 실행할 수 없습니다.

• 사용자 정의 에이전트 및 기반 에이전트는 계속 사용할 수 있습니다.