GitLab Duo Agent Platform으로 작업하는 경우 다음과 같은 문제가 발생할 수 있습니다.

로그 보기#

플로우가 생성된 후 AI > 세션으로 이동하여 플로우의 세션을 볼 수 있습니다.

Details 탭에는 CI/CD job 로그에 대한 링크가 표시됩니다. 이러한 로그에는 문제 해결 정보가 포함될 수 있습니다.

UI에 플로우가 표시되지 않음#

플로우를 실행하려고 하지만 GitLab UI에 표시되지 않는 경우:

• 프로젝트에서 최소 Developer 권한이 있는지 확인합니다.

• GitLab Duo가 켜져 있고 플로우 실행이 허용되어 있는지 확인합니다.

• 속한 그룹에 플로우를 사용할 수 있는 권한이 부여되었는지 확인합니다.

• 최상위 그룹이 올바르게 구성되었지만 개별 프로젝트에서 플로우가 보이지 않는 경우:

  프로젝트로 이동합니다.

  • AI > 플로우를 선택합니다.

  • 오른쪽 상단 모서리에서 Enable flow from group을 선택합니다.

  • 플로우를 선택한 다음 Enable을 선택합니다.

• 여전히 작동하지 않는 경우:

  최상위 그룹에서 영향받은 플로우를 비활성화하고 구성을 저장합니다.

  • 최상위 그룹에서 영향받은 플로우를 활성화하고 구성을 저장합니다.

  • 설정이 그룹 전체에 전파되기까지 몇 분간 기다립니다.

가져온 프로젝트에 대한 새 파이프라인 생성 권한 부족#

가져온 프로젝트나 템플릿에서 생성된 프로젝트에서 기본 플로우를 실행하려고 할 때 다음 오류가 발생할 수 있습니다: Error in creating workload: Insufficient permissions to create a new pipeline.

이 문제를 해결하려면:

• 최상위 그룹으로 이동합니다.

• Settings > General을 선택합니다.

• GitLab Duo features를 확장합니다.

• Flow execution 아래에서 켜고 싶은 기본 플로우를 식별합니다.

• 최상위 그룹에서 플로우를 비활성화하고 구성을 저장합니다.

• 최상위 그룹에서 같은 플로우를 활성화하고 구성을 저장합니다.

• 설정이 그룹의 프로젝트 전체에 전파되기까지 몇 분간 기다립니다.

오류: 요청은 유효하지만 Workflow가 완료하지 못했습니다#

플로우를 실행하려면 프로젝트 저장소에 최소 하나의 커밋이 있어야 합니다. 커밋이 없는 프로젝트에서 플로우를 실행하면 다음 오류가 발생합니다: Your request was valid but Workflow failed to complete it. Please try again.

이 오류는 커밋이 없는 저장소에서 플로우가 기본 브랜치를 찾을 수 없기 때문에 발생합니다.

이 문제를 해결하려면 플로우를 실행하기 전에 프로젝트에 초기 커밋을 푸시하세요. 예를 들어, README.md 파일을 추가합니다.

세션이 생성된 상태에서 멈춤#

플로우 세션이 시작되지 않는 경우:

• push 규칙이 구성되어 있는지 확인합니다.

서비스 계정을 허용하도록 push 규칙 구성#

GitLab UI에서 기본 플로우는 다음을 수행하는 서비스 계정을 사용합니다:

• 고유한 이메일 주소로 커밋을 만듭니다.

• 워크로드 파이프라인을 만듭니다.

전제 조건:

• 관리자 접근 권한.

프로젝트에 대한 push 규칙을 구성하려면:

• 서비스 계정과 관련된 이메일 주소를 찾습니다:

  오른쪽 상단 모서리에서 Admin을 선택합니다.

  • Overview > Users를 선택하고 플로우와 연관된 계정을 검색합니다. 계정은 duo-[flow-name]-[top-level-group-name] 패턴을 따릅니다.

  • 서비스 계정 사용자를 찾아 이메일 주소를 복사합니다.

• 이메일 주소가 프로젝트에 push할 수 있도록 허용합니다:

  상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.

  • Settings > Repository를 선택합니다.

  • Push rules를 확장합니다.

  • Commit author's email에서 방금 복사한 이메일 주소를 허용하는 정규 표현식을 추가합니다.

  • Save push rules를 선택합니다.

• duo/feature/ 브랜치 접두사를 허용합니다:

  Push rules 섹션에서 Branch name을 찾습니다.

  • ^duo/(fix|feature|refactor|docs/).*로 시작하는 브랜치를 허용하는 정규 표현식을 추가합니다. 예: ^(duo/feature)/.*$

  • Save push rules를 선택합니다.

인스턴스에 대한 push 규칙을 만들려면:

• 오른쪽 상단 모서리에서 Admin을 선택합니다.

• 왼쪽 사이드바에서 Push rules를 선택합니다.

• 이전 단계에 따라 Commit author's email 및 Branch name을 허용합니다.

• Save push rules를 선택합니다.

플로우 job이 시작되지 않거나 Starting job에서 멈춤#

플로우의 job이 시작되지 않거나 job이 Starting job에서 멈춰 있다면, job을 가져갈 수 있는 runner가 없는 것입니다. 플로우는 다음 요구 사항을 충족하는 runner에서 실행됩니다:

• runner에 gitlab--duo 태그가 있습니다.

• runner가 docker, docker-autoscaler 또는 kubernetes와 같이 Docker 이미지를 지원하는 executor를 사용합니다. shell executor는 지원되지 않습니다.

• runner가 인스턴스 runner이거나 최상위 그룹에 할당된 그룹 runner입니다. 하위 그룹이나 프로젝트로 범위가 지정된 runner는 duo_runner_restrictions 기능 플래그가 꺼져 있지 않는 한 플로우 job을 가져가지 않습니다.

이 문제를 해결하려면:

• GitLab.com에서는 프로젝트에 호스팅된 runner가 켜져 있는지 확인합니다. 호스팅된 runner는 기본적으로 모든 요구 사항을 충족합니다.

• 자체 runner를 사용하는 경우, 최소 하나의 runner가 요구 사항을 충족하는지 확인합니다:

  상단 표시줄에서 Search or go to를 선택하고 프로젝트 또는 최상위 그룹을 찾습니다.

  • 왼쪽 사이드바에서 Build > Runners를 선택합니다.

  • gitlab--duo 태그가 있는 runner가 온라인 상태인지 확인합니다.

• 요구 사항을 충족하는 runner가 없으면 플로우를 실행할 runner를 구성합니다.

오류: GitLab Duo에서 리뷰를 요청하는 중에 문제가 발생했습니다#

GitLab 18.8 이하에서는 Code Review Flow 실패 시 이 오류 메시지가 표시됩니다. 다음은 일반적인 근본 원인입니다:

• 기본 플로우 서비스 계정이 생성되지 않았습니다.

• 그룹 멤버십 잠금이 서비스 계정의 프로젝트 추가를 방지하고 있습니다.

• 여러 GitLab Duo 네임스페이스에 속해 있고 기본 네임스페이스가 설정되지 않았습니다.

GitLab 18.9 이상에서는 보다 구체적인 오류 메시지가 대신 표시됩니다. 자세한 내용은 Code Review Flow 문제 해결을 참조하세요.

기본 플로우 서비스 계정이 생성되지 않음#

기본 플로우가 켜져 있지만 작동하지 않는 경우, 최상위 그룹의 서비스 계정이 성공적으로 생성되지 않았을 수 있습니다.

서비스 계정이 존재하는지 확인하려면:

• 상단 표시줄에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.

• 왼쪽 사이드바에서 Settings > Service Accounts를 선택합니다.

• duo-[flow-name]-[top-level-group-name]이라는 이름의 계정을 찾습니다.

계정이 없는 경우 CascadeSyncFoundationalFlowsWorker가 계정을 만드는 데 실패했을 수 있습니다. 계정이 없음을 확인하려면 Sidekiq 로그에서 다음 오류를 확인하세요:

{
  "severity": "ERROR",
  "meta.caller_id": "Ai::Catalog::Flows::CascadeSyncFoundationalFlowsWorker",
  "message": "Cannot obtain an exclusive lease. There must be another instance already in execution.",
  "lease_key": "sidekiq:concurrency_limit:{ai/catalog/flows/cascade_sync_foundational_flows_worker}",
  "lease_timeout": 600
}

이 문제를 해결하려면 기본 플로우를 끄고 10분 후에 다시 켜세요.

그룹 멤버십 잠금#

최상위 그룹에 대해 멤버십이 잠겨 있는 경우, 서비스 계정을 필요한 프로젝트에 추가할 수 없기 때문에 기본 플로우가 자동으로 실패합니다.

이 문제를 해결하려면:

• 상단 표시줄에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.

• 왼쪽 사이드바에서 Settings > General을 선택합니다.

• Permissions and group features를 확장합니다.

• Users cannot be added to projects in this group 체크박스를 선택 해제한 후 Save changes를 선택합니다.

• 기본 플로우를 끄고 Save changes를 선택합니다.

• 기본 플로우를 다시 켠 후 Save changes를 선택합니다.

• Users cannot be added to projects in this group 체크박스를 선택한 후 Save changes를 선택합니다.

기본 GitLab Duo 네임스페이스가 설정되지 않음#

GitLab 18.3 이상에서 여러 GitLab Duo 네임스페이스에 속해 있고 기본 네임스페이스가 설정되지 않은 경우 GitLab Duo Agent Platform이 꺼집니다.

GitLab 18.8 이하에서는 다음 오류 메시지가 표시될 수 있습니다:

Something went wrong while requesting a review from GitLab Duo.

GitLab 18.9 이상에서는 네임스페이스 관련 오류가 발생할 수 있습니다.

이 문제를 해결하려면 기본 GitLab Duo 네임스페이스를 설정하세요.

오류: SSL certificate OpenSSL verify result: unable to get local issuer certificate (20)#

커스텀 또는 자체 서명된 CA 인증서를 사용하는 GitLab Self-Managed 인스턴스에서, 초기 git clone(get_sources 단계) 중에 GitLab Duo Agent Platform 작업이 실패할 때 이 메시지가 표시될 수 있습니다.

이는 GitLab Duo Agent Platform 작업이 에이전트 샌드박스를 강화하기 위해 GIT_CONFIG_GLOBAL=/dev/null 및 GIT_CONFIG_NOSYSTEM=1을 설정하기 때문입니다. 이러한 변수는 Git이 시스템 및 전역 구성 파일을 읽지 못하게 합니다. 이로 인해 get_sources 중에 CA 인증서 경로를 삽입하는 runner의 메커니즘이 중단됩니다.

플로우를 실행하지 않는 CI/CD 작업은 영향을 받지 않습니다. 이 문제는 GitLab Duo Agent Platform의 워크로드 파이프라인에만 해당됩니다.

이 문제를 해결하려면 config.toml 파일에서 runner 레벨의 GIT_SSL_CAINFO 환경 변수를 설정하고 CA 인증서를 컨테이너에 마운트하세요:

[[runners]]
  environment = ["GIT_SSL_CAINFO=/etc/gitlab-runner/certs/ca.crt"]
  [runners.docker]
    volumes = ["/path/to/your/ca-bundle.crt:/etc/gitlab-runner/certs/ca.crt:ro"]

/path/to/your/ca-bundle.crt를 runner 호스트의 CA 인증서 번들 경로로 교체하세요. 파일은 루트 CA 및 중간 인증서를 포함하는 PEM 형식의 CA 번들이어야 합니다.

CI/CD 변수로 설정하고 싶을 수 있지만, 커스텀 CI/CD 변수는 GitLab Duo Agent Platform 작업에서 사용할 수 없습니다. 대신 runner의 config.toml environment 지시어를 사용해야 합니다.

커스텀 CA를 통해 GitLab Duo CLI를 GitLab 인스턴스에 연결하려면 NODE_EXTRA_CA_CERTS를 동일한 environment 줄에 추가하세요:

[[runners]]
  environment = [
    "GIT_SSL_CAINFO=/etc/gitlab-runner/certs/ca.crt",
    "NODE_EXTRA_CA_CERTS=/etc/gitlab-runner/certs/ca.crt"
  ]
  [runners.docker]
    volumes = ["/path/to/your/ca-bundle.crt:/etc/gitlab-runner/certs/ca.crt:ro"]

GitLab Duo CLI가 Anthropic Sandbox Runtime(SRT)에서 실행되는 경우 runner environment 변수가 도달하지 않을 수 있습니다. 이 변경 후에도 TLS 오류가 지속되면 agent-config.yml의 setup_script에서 대신 NODE_EXTRA_CA_CERTS를 설정하세요. setup_script는 컨테이너 내부에서 실행되며 샌드박스에 의해 필터링되지 않습니다.

GIT_SSL_CAINFO 변수는 GitLab Duo CLI가 시작되기 전에 발생하는 Git 작업을 처리합니다. GitLab Duo CLI 인증서 구성에 대해서는 인증서 오류를 참조하세요.

WebSocket 오류 1006 또는 404로 연결 실패#

GitLab Duo CLI, GitLab Language Server 및 IDE 클라이언트(GitLab for VS Code, JetBrains IDE용 GitLab Duo 플러그인, GitLab for Visual Studio)는 WebSocket 연결을 통해 GitLab Duo Agent Platform에 연결합니다. 이 연결이 실패하면 클라이언트는 다음 오류 중 하나를 기록합니다:

• 1006: WebSocket이 종료 핸드셰이크 없이 비정상적으로 닫혔습니다.

• 404: 클라이언트가 다음 WebSocket 엔드포인트에 도달할 수 없습니다:

  GitLab Duo Non-Agentic의 경우: /-/cable.

  • GitLab Duo Agent Platform의 경우: wss://\<instance\>/api/v4/ai/duo_workflows/ws.

이러한 오류는 일반적으로 네트워크의 커스텀 인증 기관(CA), HTTP 프록시, TLS 검사 프록시 또는 상호 TLS(mTLS) 프록시가 연결을 방해할 때 발생합니다. 이 문제를 해결하려면 다음 원인을 차례로 확인하세요.

커스텀 CA 인증서#

네트워크에서 커스텀 또는 자체 서명 CA 인증서를 사용하는 경우, 클라이언트는 GitLab 인스턴스에 대한 연결을 검증할 수 없습니다. 클라이언트에 인증서를 구성하세요:

• GitLab Duo CLI의 경우 NODE_EXTRA_CA_CERTS 환경 변수를 CA 인증서 경로로 설정합니다.

• IDE 클라이언트의 경우 GitLab Language Server가 인증서를 관리합니다. JetBrains IDE는 인증서 오류를 참조하세요. VS Code는 커스텀 인증서 관련 오류를 참조하세요.

HTTP 프록시#

네트워크에 HTTP 프록시가 필요한 경우, 클라이언트에 프록시를 구성하세요:

• GitLab Duo CLI의 경우 HTTP_PROXY, HTTPS_PROXY 및 NO_PROXY 환경 변수를 설정합니다.

• IDE 클라이언트의 경우 프록시를 사용하도록 Language Server를 구성합니다.

WebSocket 트래픽 차단#

로그에 404 오류가 표시되거나 /-/cable WebSocket 엔드포인트 대신 HTTP/1.1 응답이 표시되면, GitLab 인스턴스가 인바운드 WebSocket 연결을 차단하고 있을 수 있습니다. 관리자에게 GitLab 인스턴스로의 WebSocket 트래픽을 허용하도록 요청하세요.

mTLS 또는 TLS 검사 프록시#

네트워크가 TLS 검사(SSL 가로채기) 프록시를 통해 트래픽을 라우팅하는 경우, 다음 두 가지를 모두 구성하세요:

• HTTPS_PROXY 환경 변수를 프록시 URL로 설정합니다.

• 프록시의 CA 인증서를 추가합니다.

GitLab Duo CLI, JetBrains IDE용 GitLab Duo 플러그인 및 GitLab for Visual Studio에는 두 가지 알려진 이슈가 있습니다:

• 프록시 URL이 https://를 사용하면 WebSocket 연결이 실패합니다. 가능하면 http:// 프록시 URL을 사용하세요.

• 이러한 클라이언트는 mTLS를 위한 클라이언트 인증서를 제시할 수 없습니다.

자세한 내용은 이슈 2527을 참조하세요. GitLab for VS Code는 영향을 받지 않습니다.

IDE에서 문제 해결#

IDE에서 GitLab Duo Agent Platform으로 작업하는 중 문제가 발생하면, GitLab Duo가 켜져 있고 올바르게 연결되어 있는지 먼저 확인합니다.

• GitLab Duo Agent Platform 사전 요구 사항을 충족해야 합니다.

• Admin 모드가 비활성화되어 있어야 합니다.

• 프로젝트가 그룹 네임스페이스에 있어야 합니다.

• 기본 GitLab Duo 네임스페이스가 설정되어 있거나 GitLab Duo 액세스 권한이 있는 프로젝트가 열려 있어야 합니다.

추가 지원은 확장 및 IDE의 문제 해결 페이지를 참조하세요:

• GitLab for VS Code

• GitLab Duo plugin for JetBrains IDEs

• GitLab for Visual Studio

구성 진단 스크립트 실행#

관련 기능 문서에서 GitLab Duo Agent Platform 문제의 원인을 파악할 수 없는 경우 진단 스크립트를 실행하여 구성을 확인합니다.

스크립트는 GitLab Duo Agent Platform 기능에 필요한 전체 구성 체인을 확인합니다:

• 라이선스 유효성 및 플랜.

• 인스턴스 수준 GitLab Duo 설정.

• gitlab--duo 태그가 있는 CI/CD runner.

• 네임스페이스 및 프로젝트 GitLab Duo 설정.

• 기본 플로우 및 해당 서비스 계정.

• Code Review Flow 가용성 및 자동 리뷰 설정과 같은 기능 가용성.

전제 조건:

• GitLab 18.8 이상

GitLab 19.0 이상에서 진단 스크립트를 실행하려면:

• 내장된 gitlab:duo:verify_setup Rake 작업을 실행합니다. <group/project>를 프로젝트의 전체 경로로 교체합니다. 예: gitlab-org/gitlab.

  예시:

sudo gitlab-rake "gitlab:duo:verify_setup[<group/project>]"

GitLab 18.8에서 GitLab 18.11까지에서 진단 스크립트를 실행하려면:

Linux package (Omnibus)

• verify_setup.rb를 다운로드합니다.

• verify_setup.rb 파일을 GitLab 서버에 복사합니다.

• 스크립트를 실행합니다. <group/project>를 프로젝트의 전체 경로로 교체합니다. 예: gitlab-org/gitlab.

sudo gitlab-rails runner "load '/tmp/verify_setup.rb'; Gitlab::Duo::Administration::VerifySetup.new('<group/project>').execute"

Docker

• verify_setup.rb를 다운로드합니다.

• verify_setup.rb 파일을 컨테이너에 복사합니다.

• 스크립트를 실행합니다. <group/project>를 프로젝트의 전체 경로로 교체합니다. 예: gitlab-org/gitlab.

docker cp verify_setup.rb <container-id>:/tmp/verify_setup.rb
docker exec -it <container-id> gitlab-rails runner \
"load '/tmp/verify_setup.rb'; Gitlab::Duo::Administration::VerifySetup.new('<group/project>').execute"

Self-compiled (source)

• verify_setup.rb를 다운로드합니다.

• verify_setup.rb 파일을 GitLab 서버에 복사합니다.

• GitLab 애플리케이션 디렉터리에서 스크립트를 실행합니다. <group/project>를 프로젝트의 전체 경로로 교체합니다. 예: gitlab-org/gitlab.

sudo -u git bundle exec rails runner \
"load '/tmp/verify_setup.rb'; Gitlab::Duo::Administration::VerifySetup.new('<group/project>').execute"

Helm chart (Kubernetes)

• verify_setup.rb를 다운로드합니다.

• verify_setup.rb 파일을 toolbox pod에 복사합니다.

• 스크립트를 실행합니다. <group/project>를 프로젝트의 전체 경로로 교체합니다. 예: gitlab-org/gitlab.

# Find the toolbox pod
kubectl get pods --namespace <namespace> -lapp=toolbox

kubectl cp verify_setup.rb <namespace>/<toolbox-pod-name>:/tmp/verify_setup.rb
kubectl exec -it <toolbox-pod-name> -- gitlab-rails runner \
"load '/tmp/verify_setup.rb'; Gitlab::Duo::Administration::VerifySetup.new('<group/project>').execute"

관련 주제#

• GitLab Duo Agentic Chat 문제 해결

• Code Review Flow 문제 해결

• GitLab MCP 클라이언트 문제 해결

• GitLab MCP 서버 문제 해결