GitLab Duo 에이전트는 병렬로 동작해 코드를 작성하고 결과를 조사하며 여러 작업을 동시에 수행하도록 돕습니다.

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

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

• 주변 컨텍스트와 리포지터리 코드를 읽고 분석합니다.
• 프로젝트 권한을 준수하고 감사 추적을 유지하면서 취해야 할 적절한 조치를 결정합니다.
• CI/CD 파이프라인을 실행하고, 머지 준비가 된 변경 사항이나 인라인 코멘트로 GitLab 안에서 응답합니다.

사전 요구 사항#

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

보안 고려 사항#

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

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

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

Duo Agent Platform의 보안 위협과 완화 방안에 관한 더 넓은 개요는 Duo Agent Platform 보안 위협 문서를 참고합니다.

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

다음 통합은 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 Agent#

Claude Code Agent by GitLab은 GitLab 관리형 자격 증명을 사용하며 추가 구성이 필요하지 않습니다.

Codex Agent#

Codex Agent by GitLab은 GitLab 관리형 자격 증명을 사용하며 추가 구성이 필요하지 않습니다.

Amazon Q Developer Agent#

Amazon Q Developer Agent는 GitLab 관리형 자격 증명을 사용하지 않습니다. 이 에이전트를 사용하려면 자체 자격 증명을 제공해야 합니다.

Amazon Q Developer Agent를 사용하려면 다음과 같이 합니다.

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

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION_NAME
  • AMAZON_Q_SIGV4

Develop with Gemini Agent#

Develop with Gemini Agent는 GitLab 관리형 자격 증명을 사용하지 않습니다. 이 에이전트를 사용하려면 자체 자격 증명을 제공해야 합니다.

Develop with Gemini Agent를 사용하려면 다음과 같이 합니다.

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

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

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

관리자는 자신의 GitLab 인스턴스에 Claude Agent와 Codex Agent를 추가할 수 있습니다.

사전 요구 사항:

• 관리자여야 합니다.

인스턴스에 외부 에이전트를 추가하려면 다음과 같이 합니다.

sudo gitlab-rake gitlab:ai_catalog:seed_external_agents

bundle exec rake gitlab:ai_catalog:seed_external_agents

API로 외부 에이전트를 추가할 수도 있습니다.

자격 증명 액세스#

외부 에이전트는 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 API에 인증하는 방법은 GitLab API 인증을 참고합니다.

지원되는 모델#

GitLab 관리형 자격 증명에서는 다음 AI 모델이 지원됩니다.

Anthropic Claude:

• claude-haiku-4-5-20251001
• claude-opus-4-5-20251101
• claude-opus-4-6
• claude-sonnet-4-20250514
• claude-sonnet-4-5-20250929
• claude-sonnet-4-6

OpenAI Codex:

• gpt-5
• gpt-5-mini-2025-08-07
• gpt-5.1
• gpt-5.1-2025-11-13
• gpt-5.2-2025-12-11
• gpt-5.3-codex
• gpt-5.4-2026-03-05
• gpt-5.4-mini
• gpt-5.4-nano

CI/CD 변수 구성#

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

프로젝트 설정에서 변수를 추가하거나 업데이트하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
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 변수를 사용할 수 있습니다.

GitLab API 인증#

모든 외부 에이전트는 환경 변수 AI_FLOW_GITLAB_TOKEN으로 설정된 GitLab OAuth 토큰을 받습니다. 이 토큰은 부여된 스코프로 제한됩니다. ai_workflows 스코프가 있는 GitLab API 엔드포인트에만 액세스할 수 있습니다. 해당 스코프를 벗어난 엔드포인트는 토큰을 올바르게 보내도 거부됩니다.

외부 에이전트에서 GitLab API를 호출하려면 AI_FLOW_GITLAB_TOKEN을 Authorization: Bearer 토큰으로 보냅니다. PRIVATE-TOKEN 헤더로 토큰을 보내면 API는 401 Unauthorized를 반환합니다.

curl --header "Authorization: Bearer $AI_FLOW_GITLAB_TOKEN" \
  "https://$AI_FLOW_GITLAB_HOSTNAME/api/v4/user"

에이전트에서 glab CLI를 사용하려면 토큰을 ~/.config/glab-cli/config.yml에 기록하고 glab이 토큰을 올바르게 보내도록 is_oauth2: "true"를 설정합니다.

hosts:
  $AI_FLOW_GITLAB_HOSTNAME:
    token: $AI_FLOW_GITLAB_TOKEN
    is_oauth2: "true"

GitLab 관리형 Claude 에이전트와 Codex 에이전트도 같은 패턴을 사용합니다. 동작하는 예시는 외부 에이전트 구성 예시를 참고합니다.

ID 토큰으로 인증#

서드파티 OpenID Connect(OIDC) 서비스로 커스텀 외부 에이전트를 인증하려면 에이전트 구성에 ID 토큰을 선언합니다. GitLab CI/CD가 서명된 JSON web token(JWT)을 생성해 에이전트 job에 주입합니다.

ID 토큰을 사용하면 장기 자격 증명을 저장하지 않고 인증할 수 있습니다. 예를 들어 시크릿 관리자에서 시크릿을 가져오거나 아티팩트에 서명할 수 있습니다.

ID 토큰을 구성하려면 외부 에이전트 구성에 id_tokens 블록을 추가합니다. 각 토큰에는 aud(audience) 클레임이 필요합니다.

injectGatewayToken: true
image: node:22-slim
commands:
  - my-authentication-script.sh "$VAULT_ID_TOKEN"
id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

aud 클레임은 단일 문자열이거나 문자열 목록일 수 있습니다. 각 토큰은 토큰 이름을 사용하는 환경 변수로 에이전트 job에서 사용할 수 있습니다.

토큰 페이로드에 관한 자세한 내용은 ID 토큰을 사용한 OpenID Connect(OIDC) 인증을 참고합니다.

에이전트 활성화#

이슈, 머지 리퀘스트, 토론에서 에이전트를 트리거하려면 에이전트를 활성화합니다.

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

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

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

프로젝트에서 활성화#

외부 에이전트가 이미 최상위 그룹에서 활성화되어 있으면 그 그룹의 프로젝트에서 활성화할 수 있습니다.

사전 요구 사항:

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

프로젝트에서 외부 에이전트를 활성화하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 AI > Agents를 선택합니다.
3. 오른쪽 위에서 Enable agent from group을 선택합니다.
4. 드롭다운 목록에서 활성화할 외부 에이전트를 선택합니다.
5. Add triggers에서 다음을 선택합니다.
   • 하나 이상의 트리거 이벤트 유형.
   • 트리거 이벤트 유형에 필요한 경우 트리거 이벤트 액션.
6. Enable을 선택합니다.

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

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

외부 에이전트 사용#

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.
• GitLab 관리형 외부 에이전트와 AI Catalog에서 만든 커스텀 외부 에이전트의 경우, 해당 외부 에이전트가 프로젝트에서 활성화되어 있어야 합니다.
• 에이전트가 에이전트 생성 브랜치(^duo/(fix|feature|refactor|docs/).*`로 시작하는 브랜치)에 푸시할 수 있게 하려면 브랜치 규칙을 만들어야 할 수 있습니다.

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

2. 서비스 계정 사용자를 멘션하거나 담당자로 지정하거나 검토를 요청합니다. 예를 들면 다음과 같습니다.

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

3. 외부 에이전트가 작업을 완료하면 확인 메시지와 함께 머지 준비가 된 변경 사항 또는 인라인 코멘트가 표시됩니다.

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

GitLab Self-Managed에서 ai_catalog_create_third_party_flows 기능 플래그가 활성화되어 있으면 AI Catalog로 외부 에이전트를 만들고 자신의 환경에서 실행되도록 구성할 수 있습니다.

GitLab.com에서는 커스텀 외부 에이전트를 만들 수 없습니다. 대신 GitLab 관리형 외부 에이전트를 사용합니다.

권장하는 워크플로는 다음과 같습니다.

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

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

원한다면 외부 에이전트를 수동으로 만들 수도 있습니다.

에이전트 가시성#

커스텀 외부 에이전트를 만들 때는 이를 관리할 프로젝트를 선택하고, 에이전트를 공개, 비공개, 제한 중 어느 것으로 할지 선택합니다.

공개 에이전트는 다음과 같습니다.

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

제한 에이전트는 다음과 같습니다.

• 관리 프로젝트의 최상위 그룹에 속한 모든 프로젝트의 멤버가 보고 사용할 수 있습니다.
• 같은 최상위 그룹의 다른 프로젝트에서 활성화할 수 있습니다.
• 해당 최상위 그룹 외부에서는 보거나 켤 수 없습니다.
• Explore의 AI Catalog에서는 볼 수 없습니다.
• Explore의 AI Catalog가 아니라 프로젝트에서만 만들 수 있습니다.

해당 최상위 그룹 외부의 프로젝트가 에이전트를 켠 경우에는 공개 에이전트를 제한 에이전트로 바꿀 수 없습니다.

비공개 에이전트는 다음과 같습니다.

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

관리 프로젝트가 아닌 프로젝트가 에이전트를 켠 경우에는 공개 또는 제한 에이전트를 비공개로 바꿀 수 없습니다.

AI Catalog에서 에이전트 생성#

먼저 AI Catalog에서 외부 에이전트를 만듭니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

외부 에이전트를 만들려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 AI > Agents를 선택합니다.
3. New agent를 선택합니다.
4. Basic information에서 다음을 수행합니다.
   1. Display name에 이름을 입력합니다.
   2. Description에 설명을 입력합니다.
5. Visibility & access의 Visibility에서 Private, Restricted 또는 Public을 선택합니다.
6. Configuration에서 다음을 수행합니다.
   1. External을 선택합니다.
   2. 외부 에이전트 구성을 입력합니다. 직접 YAML을 작성하거나 예시 구성을 편집할 수 있습니다.
7. Create agent를 선택합니다.

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

YAML 구성에는 최대 크기가 있습니다. 자세한 내용은 구성 크기 제한을 참고합니다.

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

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 관리형 외부 에이전트와 커스텀 외부 에이전트가 모두 포함됩니다.
• 기존 외부 에이전트가 프로젝트의 AI > Agents > Enabled에 더 이상 표시되지 않습니다.
• 프로젝트에서 만든 외부 에이전트는 AI > Agents > Managed에 표시되지만 수정하거나 실행할 수 없습니다.
• 커스텀 에이전트와 파운데이셔널 에이전트는 계속 사용할 수 있습니다.