GitLab Duo Agent Platform 문제 해결

요약

GitLab Duo Agent Platform을 사용할 때 다음과 같은 문제가 발생할 수 있습니다. 플로를 만든 뒤에는 AI > Sessions로 이동해 해당 플로의 세션을 볼 수 있습니다. Details 탭에는 CI/CD job 로그 링크가 표시됩니다.

GitLab Duo Agent Platform을 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

로그 보기#

플로를 만든 뒤에는 AI > Sessions로 이동해 해당 플로의 세션을 볼 수 있습니다.

Details 탭에는 CI/CD job 로그 링크가 표시됩니다. 이 로그에는 문제 해결에 필요한 정보가 들어 있을 수 있습니다.

UI에 플로가 보이지 않음#

플로를 실행하려 하는데 GitLab UI에 보이지 않는다면 다음을 확인합니다.

프로젝트에서 최소 Developer 권한이 있는지 확인합니다.
GitLab Duo가 켜져 있고 플로 실행이 허용되어 있는지 확인합니다.
현재 그룹에 플로 사용 권한이 부여되어 있는지 확인합니다.
최상위 그룹은 올바르게 설정되어 있는데 개별 프로젝트에서 플로가 보이지 않는다면 다음을 수행합니다.
1. 해당 프로젝트로 이동합니다.
2. AI > Flows를 선택합니다.
3. 오른쪽 위 모서리에서 Enable flow from group을 선택합니다.
4. 플로를 선택한 다음 Enable을 선택합니다.
그래도 해결되지 않으면 다음을 수행합니다.
1. 최상위 그룹에서 해당 플로를 비활성화하고 설정을 저장합니다.
2. 최상위 그룹에서 해당 플로를 다시 활성화하고 설정을 저장합니다.
3. 설정이 그룹 전체에 반영될 때까지 몇 분 기다립니다.

가져온 프로젝트에서 새 파이프라인을 만들 권한 부족#

가져온 프로젝트나 템플릿으로 만든 프로젝트에서 파운데이셔널 플로를 실행하면 Error in creating workload: Insufficient permissions to create a new pipeline 오류가 발생할 수 있습니다.

이 문제를 해결하려면 다음을 수행합니다.

최상위 그룹으로 이동합니다.
Settings > General을 선택합니다.
GitLab Duo features를 확장합니다.
Flow execution에서 켜려는 파운데이셔널 플로를 확인합니다.
최상위 그룹에서 해당 플로를 비활성화하고 설정을 저장합니다.
최상위 그룹에서 같은 플로를 다시 활성화하고 설정을 저장합니다.
설정이 그룹 내 프로젝트에 반영될 때까지 몇 분 기다립니다.

오류: `Your request was valid but Workflow failed to complete it`#

플로를 실행하려면 프로젝트 리포지터리에 커밋이 하나 이상 있어야 합니다. 커밋이 없는 프로젝트에서 플로를 실행하면 다음 오류가 발생합니다. Your request was valid but Workflow failed to complete it. Please try again.

커밋이 없는 리포지터리에서는 플로가 기본 브랜치를 찾지 못하기 때문에 이 오류가 발생합니다.

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

오류: `Workflow could not use your token to connect to your GitLab instance`#

GitLab Duo CLI나 IDE에서 GitLab Duo Agent Platform을 사용할 때 Workflow could not use your token to connect to your GitLab instance. 오류가 발생할 수 있습니다.

이 문제는 다음과 같은 경우에 발생할 수 있습니다.

GitLab Duo Agent Platform 체험판을 사용 중입니다.
체험판에 포함되지 않은 최신 고성능(frontier) 모델을 선택했습니다.
이전 버전의 GitLab Duo CLI 또는 에디터 확장 기능을 사용 중입니다.

이 문제를 해결하려면 다음 중 하나를 수행합니다.

사용 가능한 다른 모델을 선택합니다. 자세한 내용은 모델 선택을 참고합니다.
GitLab Credits를 구매합니다.

더 자세한 오류 메시지를 확인하려면 GitLab Duo CLI 또는 에디터 확장 기능을 최신 버전으로 업데이트합니다.

자세한 내용은 GitLab Duo Agent Platform 체험판을 참고합니다.

세션이 created 상태에서 멈춤#

플로의 세션이 시작되지 않는다면 다음을 확인합니다.

푸시 규칙이 올바르게 설정되어 있는지 확인합니다.

서비스 계정을 허용하도록 푸시 규칙 설정#

GitLab UI에서 파운데이셔널 플로는 다음과 같이 동작하는 서비스 계정을 사용합니다.

자체 이메일 주소로 커밋을 생성합니다.
워크로드 파이프라인을 생성합니다.

사전 요구 사항:

관리자 접근 권한이 필요합니다.

프로젝트의 푸시 규칙을 설정하려면 다음을 수행합니다.

서비스 계정에 연결된 이메일 주소를 확인합니다.
1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. Overview > Users를 선택하고 해당 플로에 연결된 계정을 검색합니다. 계정 이름은 duo-[flow-name]-[top-level-group-name] 형식을 따릅니다.
3. 서비스 계정 사용자를 찾아 이메일 주소를 복사합니다.
해당 이메일 주소가 프로젝트에 푸시할 수 있도록 허용합니다.
1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. Settings > Repository를 선택합니다.
3. Push rules를 확장합니다.
4. Commit author's email에 방금 복사한 이메일 주소를 허용하는 정규 표현식을 추가합니다.
5. Save push rules를 선택합니다.
duo/ 브랜치 접두사를 허용합니다.
1. Push rules 절에서 Branch name을 찾습니다.
2. duo/fix/, duo/feature/, duo/refactor/, duo/docs/로 시작하는 브랜치를 허용하는 정규 표현식을 추가합니다. 예를 들면 ^duo/(fix|feature|refactor|docs)/.* 입니다.
3. Save push rules를 선택합니다.

인스턴스의 푸시 규칙을 만들려면 다음을 수행합니다.

오른쪽 위 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Push rules를 선택합니다.
앞의 단계를 따라 Commit author's email과 Branch name을 허용합니다.
Save push rules를 선택합니다.

플로의 job 또는 세션이 시작되지 않음#

플로의 job 이 시작되지 않거나 Starting job에서 멈춘다면, 그 job을 가져갈 러너가 없는 것입니다. 세션 페이지(AI > Sessions)에는 Session failed to start 경고가 표시됩니다.

플로는 다음 요건을 충족하는 러너에서 실행됩니다.

러너에 gitlab--duo 태그가 있습니다.
러너가 docker, docker-autoscaler, kubernetes처럼 Docker 이미지를 지원하는 실행기를 사용합니다. shell 실행기는 지원하지 않습니다.
러너가 인스턴스 러너이거나 최상위 그룹에 할당된 그룹 러너입니다. 하위 그룹이나 프로젝트로 범위가 한정된 러너는 duo_runner_restrictions 기능 플래그를 끄지 않는 한 플로 job을 가져가지 않습니다.

이 문제를 해결하려면 다음을 수행합니다.

GitLab.com에서는 프로젝트에 호스티드 러너가 켜져 있는지 확인합니다. 호스티드 러너는 기본적으로 모든 요건을 충족합니다.
자체 러너를 사용한다면 요건을 충족하는 러너가 하나 이상 있는지 확인합니다.
1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 최상위 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Build > Runners를 선택합니다.
3. gitlab--duo 태그가 있는 러너가 온라인 상태인지 확인합니다.
선택 사항. 프로젝트 설정에서 러너 구성을 확인합니다. 이 확인은 태그, 실행기, 범위를 함께 점검합니다.
요건을 충족하는 러너가 없다면 플로를 실행할 러너를 설정합니다.

러너가 모든 요건을 충족하는데도 job 이 시작되지 않는다면 다음을 확인합니다.

네임스페이스가 컴퓨팅 분을 모두 사용했고, 이 경우 호스티드 러너 접근 권한도 함께 사라집니다. 할당량 소진은 러너 가용성 문제처럼 보일 수 있습니다.
최상위 그룹이 IP 주소로 접근을 제한하고 있습니다. 호스티드 러너는 허용 목록에 추가할 수 없는 동적 IP 주소를 사용하므로 해당 그룹의 플로를 실행할 수 없습니다. 이 경우 최상위 그룹에 자체 러너를 설정합니다.

오류: `Something went wrong while requesting a review from 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 인증서나 자체 서명 CA 인증서를 사용하는 GitLab Self-Managed 인스턴스에서는, GitLab Duo Agent Platform job 이 최초 git clone(get_sources 단계)에서 실패할 때 이 메시지가 표시될 수 있습니다.

이는 GitLab Duo Agent Platform job 이 에이전트 샌드박스를 강화하려고 GIT_CONFIG_GLOBAL=/dev/null과 GIT_CONFIG_NOSYSTEM=1을 설정하기 때문입니다. 이 변수들은 Git 이 시스템 설정 파일과 전역 설정 파일을 읽지 못하게 합니다. 그 결과 러너가 get_sources 중에 CA 인증서 경로를 주입하는 방식이 동작하지 않습니다.

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

이 문제를 해결하려면 config.toml 파일에서 러너 수준으로 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는 러너 호스트에 있는 CA 인증서 번들 경로로 바꿉니다. 이 파일은 루트 CA와 중간 인증서를 포함하는 PEM 형식의 CA 번들이어야 합니다.

이 값을 CI/CD 변수로 설정하려고 할 수 있지만, 사용자 지정 CI/CD 변수는 GitLab Duo Agent Platform job에서 사용할 수 없습니다. 대신 러너의 config.toml environment 지시문을 사용해야 합니다.

사용자 지정 CA를 거쳐 GitLab Duo CLI를 GitLab 인스턴스에 연결하려면 같은 environment 줄에 NODE_EXTRA_CA_CERTS를 추가합니다.

[[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) 안에서 실행됩니다. 다음 인증서, 프록시, 로케일 변수가 job에 설정되어 있으면 샌드박스로 전달됩니다.

NODE_EXTRA_CA_CERTS
HTTP_PROXY, HTTPS_PROXY, NO_PROXY
소문자 대응 변수 http_proxy, https_proxy, no_proxy
LANG, LC_ALL. 샌드박스가 이미지의 로케일을 유지하도록 합니다.

이 변수는 러너의 environment 지시문에 설정하거나 agent-config.yml 파일의 setup_script에서 내보냅니다. 다른 변수는 전달되지 않습니다.

이 변수는 GitLab 인스턴스로의 연결뿐 아니라 샌드박스의 모든 Node.js 네트워크 트래픽에 적용됩니다. NODE_EXTRA_CA_CERTS는 파일을 가리키므로 앞에서 설명한 대로 CA 인증서를 컨테이너에 마운트합니다.

NODE_TLS_REJECT_UNAUTHORIZED를 0으로 설정하면 TLS 검증이 꺼지므로 이 변수는 전달되지 않습니다. 대신 NODE_EXTRA_CA_CERTS를 사용합니다.

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 인증서나 자체 서명 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을 사용합니다.

GitLab for VS Code는 영향을 받지 않습니다.

IDE 에서의 문제 해결#

IDE에서 GitLab Duo Agent Platform을 사용하다 문제가 발생하면, 먼저 GitLab Duo가 켜져 있고 정상적으로 연결되어 있는지 확인합니다.

GitLab Duo Agent Platform 사전 요구 사항을 충족합니다.
Admin mode가 비활성화되어 있습니다.
프로젝트가 그룹 네임스페이스에 있습니다.
기본 GitLab Duo 네임스페이스를 설정했거나, GitLab Duo를 사용할 수 있는 프로젝트를 열어 두었습니다.

추가 지원이 필요하면 사용 중인 확장과 IDE의 문제 해결 페이지를 참고합니다.

설정 진단 스크립트 실행#

관련 기능 문서로 GitLab Duo Agent Platform 문제의 원인을 찾지 못했다면 진단 스크립트를 실행해 설정을 점검합니다.

이 스크립트는 GitLab Duo Agent Platform 기능에 필요한 전체 설정 체인을 점검합니다.

라이선스 유효성과 플랜입니다.
인스턴스 수준 GitLab Duo 설정입니다.
gitlab--duo 태그가 있는 CI/CD 러너입니다.
네임스페이스와 프로젝트의 GitLab Duo 설정입니다.
파운데이셔널 플로와 그 서비스 계정입니다.
Code Review Flow 사용 가능 여부와 자동 검토 설정 등 기능 제공 여부입니다.

Warning

이 스크립트는 설정 데이터를 읽기만 하고 설정을 변경하지 않습니다. 출력에는 내부 설정 세부 정보가 포함될 수 있습니다. 지원 담당자와 공유하기 전에 출력을 정제합니다.

사전 요구 사항:

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 까지에서 진단 스크립트를 실행하려면 다음을 수행합니다.

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"

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"

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"
```

verify_setup.rb를 내려받습니다.
verify_setup.rb 파일을 toolbox 파드로 복사합니다.

스크립트를 실행합니다. <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 Agent Platform 문제 해결

GitLab v19.5

원문 보기

번역일: 2026-10-15

요약

GitLab Duo Agent Platform을 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

로그 보기#

플로를 만든 뒤에는 AI > Sessions로 이동해 해당 플로의 세션을 볼 수 있습니다.

Details 탭에는 CI/CD job 로그 링크가 표시됩니다. 이 로그에는 문제 해결에 필요한 정보가 들어 있을 수 있습니다.

UI에 플로가 보이지 않음#

플로를 실행하려 하는데 GitLab UI에 보이지 않는다면 다음을 확인합니다.

프로젝트에서 최소 Developer 권한이 있는지 확인합니다.
GitLab Duo가 켜져 있고 플로 실행이 허용되어 있는지 확인합니다.
현재 그룹에 플로 사용 권한이 부여되어 있는지 확인합니다.
최상위 그룹은 올바르게 설정되어 있는데 개별 프로젝트에서 플로가 보이지 않는다면 다음을 수행합니다.
1. 해당 프로젝트로 이동합니다.
2. AI > Flows를 선택합니다.
3. 오른쪽 위 모서리에서 Enable flow from group을 선택합니다.
4. 플로를 선택한 다음 Enable을 선택합니다.
그래도 해결되지 않으면 다음을 수행합니다.
1. 최상위 그룹에서 해당 플로를 비활성화하고 설정을 저장합니다.
2. 최상위 그룹에서 해당 플로를 다시 활성화하고 설정을 저장합니다.
3. 설정이 그룹 전체에 반영될 때까지 몇 분 기다립니다.

가져온 프로젝트에서 새 파이프라인을 만들 권한 부족#

이 문제를 해결하려면 다음을 수행합니다.

최상위 그룹으로 이동합니다.
Settings > General을 선택합니다.
GitLab Duo features를 확장합니다.
Flow execution에서 켜려는 파운데이셔널 플로를 확인합니다.
최상위 그룹에서 해당 플로를 비활성화하고 설정을 저장합니다.
최상위 그룹에서 같은 플로를 다시 활성화하고 설정을 저장합니다.
설정이 그룹 내 프로젝트에 반영될 때까지 몇 분 기다립니다.

오류: `Your request was valid but Workflow failed to complete it`#

커밋이 없는 리포지터리에서는 플로가 기본 브랜치를 찾지 못하기 때문에 이 오류가 발생합니다.

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

오류: `Workflow could not use your token to connect to your GitLab instance`#

GitLab Duo CLI나 IDE에서 GitLab Duo Agent Platform을 사용할 때 Workflow could not use your token to connect to your GitLab instance. 오류가 발생할 수 있습니다.

이 문제는 다음과 같은 경우에 발생할 수 있습니다.

GitLab Duo Agent Platform 체험판을 사용 중입니다.
체험판에 포함되지 않은 최신 고성능(frontier) 모델을 선택했습니다.
이전 버전의 GitLab Duo CLI 또는 에디터 확장 기능을 사용 중입니다.

이 문제를 해결하려면 다음 중 하나를 수행합니다.

사용 가능한 다른 모델을 선택합니다. 자세한 내용은 모델 선택을 참고합니다.
GitLab Credits를 구매합니다.

더 자세한 오류 메시지를 확인하려면 GitLab Duo CLI 또는 에디터 확장 기능을 최신 버전으로 업데이트합니다.

자세한 내용은 GitLab Duo Agent Platform 체험판을 참고합니다.

세션이 created 상태에서 멈춤#

플로의 세션이 시작되지 않는다면 다음을 확인합니다.

푸시 규칙이 올바르게 설정되어 있는지 확인합니다.

서비스 계정을 허용하도록 푸시 규칙 설정#

GitLab UI에서 파운데이셔널 플로는 다음과 같이 동작하는 서비스 계정을 사용합니다.

자체 이메일 주소로 커밋을 생성합니다.
워크로드 파이프라인을 생성합니다.

사전 요구 사항:

관리자 접근 권한이 필요합니다.

프로젝트의 푸시 규칙을 설정하려면 다음을 수행합니다.

서비스 계정에 연결된 이메일 주소를 확인합니다.
1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. Overview > Users를 선택하고 해당 플로에 연결된 계정을 검색합니다. 계정 이름은 duo-[flow-name]-[top-level-group-name] 형식을 따릅니다.
3. 서비스 계정 사용자를 찾아 이메일 주소를 복사합니다.
해당 이메일 주소가 프로젝트에 푸시할 수 있도록 허용합니다.
1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. Settings > Repository를 선택합니다.
3. Push rules를 확장합니다.
4. Commit author's email에 방금 복사한 이메일 주소를 허용하는 정규 표현식을 추가합니다.
5. Save push rules를 선택합니다.
duo/ 브랜치 접두사를 허용합니다.
1. Push rules 절에서 Branch name을 찾습니다.
2. duo/fix/, duo/feature/, duo/refactor/, duo/docs/로 시작하는 브랜치를 허용하는 정규 표현식을 추가합니다. 예를 들면 ^duo/(fix|feature|refactor|docs)/.* 입니다.
3. Save push rules를 선택합니다.

인스턴스의 푸시 규칙을 만들려면 다음을 수행합니다.

오른쪽 위 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Push rules를 선택합니다.
앞의 단계를 따라 Commit author's email과 Branch name을 허용합니다.
Save push rules를 선택합니다.

플로의 job 또는 세션이 시작되지 않음#

플로는 다음 요건을 충족하는 러너에서 실행됩니다.

러너에 gitlab--duo 태그가 있습니다.
러너가 docker, docker-autoscaler, kubernetes처럼 Docker 이미지를 지원하는 실행기를 사용합니다. shell 실행기는 지원하지 않습니다.
러너가 인스턴스 러너이거나 최상위 그룹에 할당된 그룹 러너입니다. 하위 그룹이나 프로젝트로 범위가 한정된 러너는 duo_runner_restrictions 기능 플래그를 끄지 않는 한 플로 job을 가져가지 않습니다.

이 문제를 해결하려면 다음을 수행합니다.

GitLab.com에서는 프로젝트에 호스티드 러너가 켜져 있는지 확인합니다. 호스티드 러너는 기본적으로 모든 요건을 충족합니다.
자체 러너를 사용한다면 요건을 충족하는 러너가 하나 이상 있는지 확인합니다.
1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 최상위 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Build > Runners를 선택합니다.
3. gitlab--duo 태그가 있는 러너가 온라인 상태인지 확인합니다.
선택 사항. 프로젝트 설정에서 러너 구성을 확인합니다. 이 확인은 태그, 실행기, 범위를 함께 점검합니다.
요건을 충족하는 러너가 없다면 플로를 실행할 러너를 설정합니다.

러너가 모든 요건을 충족하는데도 job 이 시작되지 않는다면 다음을 확인합니다.

네임스페이스가 컴퓨팅 분을 모두 사용했고, 이 경우 호스티드 러너 접근 권한도 함께 사라집니다. 할당량 소진은 러너 가용성 문제처럼 보일 수 있습니다.
최상위 그룹이 IP 주소로 접근을 제한하고 있습니다. 호스티드 러너는 허용 목록에 추가할 수 없는 동적 IP 주소를 사용하므로 해당 그룹의 플로를 실행할 수 없습니다. 이 경우 최상위 그룹에 자체 러너를 설정합니다.

오류: `Something went wrong while requesting a review from 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)`#

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

이 문제를 해결하려면 config.toml 파일에서 러너 수준으로 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"]

사용자 지정 CA를 거쳐 GitLab Duo CLI를 GitLab 인스턴스에 연결하려면 같은 environment 줄에 NODE_EXTRA_CA_CERTS를 추가합니다.

[[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"]

NODE_EXTRA_CA_CERTS
HTTP_PROXY, HTTPS_PROXY, NO_PROXY
소문자 대응 변수 http_proxy, https_proxy, no_proxy
LANG, LC_ALL. 샌드박스가 이미지의 로케일을 유지하도록 합니다.

이 변수는 러너의 environment 지시문에 설정하거나 agent-config.yml 파일의 setup_script에서 내보냅니다. 다른 변수는 전달되지 않습니다.

NODE_TLS_REJECT_UNAUTHORIZED를 0으로 설정하면 TLS 검증이 꺼지므로 이 변수는 전달되지 않습니다. 대신 NODE_EXTRA_CA_CERTS를 사용합니다.

GIT_SSL_CAINFO 변수는 GitLab Duo CLI가 시작되기 전에 수행되는 Git 작업에 적용됩니다. GitLab Duo CLI의 인증서 설정은 인증서 오류를 참고합니다.

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

1006: 종료 핸드셰이크 없이 WebSocket 이 비정상적으로 닫혔습니다.
404: 클라이언트가 다음 WebSocket 엔드포인트에 연결하지 못했습니다.
- GitLab Duo Non-Agentic: /-/cable.
- GitLab Duo Agent Platform: wss://\<instance\>/api/v4/ai/duo_workflows/ws.

사용자 지정 CA 인증서#

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 트래픽 차단#

mTLS 또는 TLS 검사 프록시#

네트워크가 TLS 검사(SSL 가로채기) 프록시를 거쳐 트래픽을 전달한다면 다음 두 가지를 모두 설정합니다.

HTTPS_PROXY 환경 변수에 프록시 URL을 설정합니다.
프록시의 CA 인증서를 추가합니다.

GitLab for VS Code는 영향을 받지 않습니다.

IDE 에서의 문제 해결#

IDE에서 GitLab Duo Agent Platform을 사용하다 문제가 발생하면, 먼저 GitLab Duo가 켜져 있고 정상적으로 연결되어 있는지 확인합니다.

GitLab Duo Agent Platform 사전 요구 사항을 충족합니다.
Admin mode가 비활성화되어 있습니다.
프로젝트가 그룹 네임스페이스에 있습니다.
기본 GitLab Duo 네임스페이스를 설정했거나, GitLab Duo를 사용할 수 있는 프로젝트를 열어 두었습니다.

추가 지원이 필요하면 사용 중인 확장과 IDE의 문제 해결 페이지를 참고합니다.

설정 진단 스크립트 실행#

관련 기능 문서로 GitLab Duo Agent Platform 문제의 원인을 찾지 못했다면 진단 스크립트를 실행해 설정을 점검합니다.

이 스크립트는 GitLab Duo Agent Platform 기능에 필요한 전체 설정 체인을 점검합니다.

라이선스 유효성과 플랜입니다.
인스턴스 수준 GitLab Duo 설정입니다.
gitlab--duo 태그가 있는 CI/CD 러너입니다.
네임스페이스와 프로젝트의 GitLab Duo 설정입니다.
파운데이셔널 플로와 그 서비스 계정입니다.
Code Review Flow 사용 가능 여부와 자동 검토 설정 등 기능 제공 여부입니다.

Warning

사전 요구 사항:

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 까지에서 진단 스크립트를 실행하려면 다음을 수행합니다.

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"

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"

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"
```

verify_setup.rb를 내려받습니다.
verify_setup.rb 파일을 toolbox 파드로 복사합니다.

스크립트를 실행합니다. <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 Agent Platform 문제 해결

로그 보기#

UI에 플로가 보이지 않음#

가져온 프로젝트에서 새 파이프라인을 만들 권한 부족#

오류: Your request was valid but Workflow failed to complete it#

오류: Workflow could not use your token to connect to your GitLab instance#

세션이 created 상태에서 멈춤#

서비스 계정을 허용하도록 푸시 규칙 설정#

플로의 job 또는 세션이 시작되지 않음#

오류: Something went wrong while requesting a review from GitLab Duo#

파운데이셔널 플로 서비스 계정이 생성되지 않음#

그룹 멤버십 잠김#

기본 GitLab Duo 네임스페이스 미설정#

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

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

사용자 지정 CA 인증서#

HTTP 프록시#

WebSocket 트래픽 차단#

mTLS 또는 TLS 검사 프록시#

IDE 에서의 문제 해결#

설정 진단 스크립트 실행#

관련 주제#

GitLab Duo Agent Platform 문제 해결

로그 보기#

UI에 플로가 보이지 않음#

가져온 프로젝트에서 새 파이프라인을 만들 권한 부족#

오류: Your request was valid but Workflow failed to complete it#

오류: Workflow could not use your token to connect to your GitLab instance#

세션이 created 상태에서 멈춤#

서비스 계정을 허용하도록 푸시 규칙 설정#

플로의 job 또는 세션이 시작되지 않음#

오류: Something went wrong while requesting a review from GitLab Duo#

파운데이셔널 플로 서비스 계정이 생성되지 않음#

그룹 멤버십 잠김#

기본 GitLab Duo 네임스페이스 미설정#

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

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

사용자 지정 CA 인증서#

HTTP 프록시#

WebSocket 트래픽 차단#

mTLS 또는 TLS 검사 프록시#

IDE 에서의 문제 해결#

설정 진단 스크립트 실행#

관련 주제#

오류: `Your request was valid but Workflow failed to complete it`#

오류: `Workflow could not use your token to connect to your GitLab instance`#

오류: `Something went wrong while requesting a review from GitLab Duo`#

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

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

오류: `Your request was valid but Workflow failed to complete it`#

오류: `Workflow could not use your token to connect to your GitLab instance`#

오류: `Something went wrong while requesting a review from GitLab Duo`#

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

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