GitLab for VS Code를 사용하는 동안 다음과 같은 문제가 발생할 수 있습니다.

아래 내용으로 해결되지 않는 문제라면 지원에 필요한 정보를 수집한 후 gitlab-vscode-extension 이슈 트래커에 버그를 신고합니다.

로그#

GitLab for VS Code 확장 프로그램과, 이 확장 프로그램을 구동하는 GitLab Language Server는 문제 해결에 도움이 되는 로그를 제공합니다.

디버그 로그 활성화#

디버그 로깅을 활성화하려면:

1. VS Code에서 Settings 편집기를 엽니다.
   • macOS는 Code > Preferences > Settings를 선택합니다.
   • Windows 또는 Linux는 File > Preferences > Settings를 선택합니다.
2. Extensions > GitLab > Other를 선택합니다.
3. GitLab: Debug 아래에서 체크박스를 선택해 디버그 모드를 켭니다.
4. 창을 새로고침해 확장 프로그램을 다시 시작합니다.
   1. VS Code에서 View > Command Palette를 선택합니다.
   2. Developer: Reload Window를 입력하고 Enter를 누릅니다.

디버그 로그 보기#

디버그 로그를 보려면:

1. VS Code에서 View > Output을 선택합니다.
2. 출력 패널 오른쪽 위 모서리에서 드롭다운 목록을 선택해 GitLab 또는 GitLab Language Server 로그로 필터링합니다.
3. 오류, 경고, 연결 문제, 인증 문제가 있는지 확인합니다.

인증#

다음과 같은 인증 오류가 발생할 수 있습니다.

오류: ...can't access the OS Keychain#

macOS와 Ubuntu에서 확장 프로그램이 인증을 위해 OS Keychain에 접근하지 못하면 오류가 발생할 수 있습니다.

예를 들면 다음과 같습니다.

The GitLab extension can't access the OS Keychain.
If you use Ubuntu, see this existing issue.

Error: Cannot get password
at I.$getPassword (vscode-file://vscode-app/snap/code/97/usr/share/code/resources/app/out/vs/workbench/workbench.desktop.main.js:1712:49592)

사용 중인 운영체제에 맞는 아래 우회 방법을 따릅니다.

이 오류에 대한 자세한 내용은 다음을 참고합니다.

• 확장 프로그램 이슈 580
• 업스트림 microsoft/vscode 이슈 147515

macOS 우회 방법#

macOS에서 이 오류를 우회하려면:

1. 사용 중인 머신에서 Keychain Access를 열고 vscodegitlab.gitlab-workflow를 검색합니다.
2. 키체인에서 vscodegitlab.gitlab-workflow를 삭제합니다.
3. VS Code에서 View > Command Palette를 선택합니다.
4. GitLab: Remove Account from VS Code를 입력하고 Enter를 눌러 VS Code에서 손상된 계정을 제거합니다.
5. Command Palette를 다시 열고 GitLab: Authenticate를 실행해 계정을 다시 추가합니다.

Ubuntu 우회 방법#

Ubuntu 20.04 및 22.04에서 snap으로 VS Code를 설치하면 VS Code가 OS keychain에서 비밀번호를 읽지 못합니다. 3.44.0 이상 버전의 확장 프로그램은 안전한 토큰 저장을 위해 OS keychain을 사용합니다.

1.68.0 이전 버전의 VS Code를 사용 중이라면 다음 우회 방법 중 하나를 시도합니다.

• GitLab for VS Code 확장 프로그램을 3.43.1 버전으로 다운그레이드합니다.
• snap 대신 .deb 패키지로 VS Code를 설치합니다.
  1. snap 버전 VS Code를 제거합니다.
  2. .deb 패키지로 VS Code를 설치합니다.
  3. Ubuntu의 Password & Keys로 이동해 vscodegitlab.workflow/gitlab-tokens 항목을 찾아 제거합니다.
  4. VS Code에서 View > Command Palette를 선택합니다.
  5. Gitlab: Remove Your Account를 입력하고 Enter를 눌러 자격 증명이 없는 계정을 제거합니다.
  6. Command Palette를 다시 열고 GitLab: Authenticate를 실행해 계정을 다시 추가합니다.

VS Code 1.68.0 이상 버전을 사용 중이라면 다시 인증을 시도합니다.

1. Ubuntu의 Password & Keys로 이동해 vscodegitlab.workflow/gitlab-tokens 항목을 찾아 제거합니다.
2. VS Code에서 View > Command Palette를 선택합니다.
3. Gitlab: Remove Your Account를 입력하고 Enter를 눌러 자격 증명이 없는 계정을 제거합니다.
4. Command Palette를 다시 열고 GitLab: Authenticate를 실행해 계정을 다시 추가합니다.

GDK 사용 시 연결 및 인증 오류#

GDK와 함께 VS Code를 사용하면 시스템이 localhost에서 실행 중인 GitLab 인스턴스에 안전한 TLS 연결을 설정할 수 없다는 오류가 발생할 수 있습니다.

예를 들어 GitLab 서버로 127.0.0.1:3000을 사용하는 경우 다음과 같습니다.

Request to https://127.0.0.1:3000/api/v4/version failed, reason: Client network
socket disconnected before secure TLS connection was established

이 문제는 GDK를 http로 실행하고 GitLab 인스턴스가 https로 호스팅될 때 발생합니다.

이를 해결하려면:

1. VS Code에서 View > Command Palette를 선택합니다.
2. GitLab: Authenticate를 입력하고 Enter를 누릅니다.
3. 인스턴스의 http URL을 수동으로 입력하는 옵션을 선택하고 Enter를 누릅니다.
4. 나머지 프롬프트를 따라 인증합니다.

프로젝트 설정#

다음과 같은 프로젝트 설정 오류가 발생할 수 있습니다.

계정 및 프로젝트 설정 오류#

VS Code에서 프로젝트를 열면 GitLab ([tanuki]) 탭의 프로젝트 이름 옆에 오류 메시지가 표시될 수 있습니다. 또는 상태 표시줄에 여러 계정이나 프로젝트에 대한 경고 메시지가 표시될 수 있습니다.

이 메시지는 확장 프로그램이 어떤 리포지터리, 계정, 프로젝트를 사용할지 식별하지 못할 때 나타납니다.

이 오류를 해결하려면:

• 원격이 정의되지 않았거나 여러 원격이 설정된 경우 리포지터리에 연결을 참고합니다.
• 상태 표시줄에 Multiple GitLab Accounts가 표시되면 계정 전환을 참고합니다.
• 상태 표시줄에 **(multiple projects)**가 표시되면 프로젝트 선택을 참고합니다.

VS Code에서 Git 작업이 처음이라면, GitLab 확장 프로그램과 무관하게 이루어지는 리포지터리와 VS Code 워크스페이스 초기화에 대한 정보는 VS Code의 소스 제어를 참고합니다.

SSH 커스텀 별칭을 사용하는 Git 원격#

리포지터리 원격이 SSH 커스텀 별칭을 사용하면 확장 프로그램이 리포지터리를 GitLab 프로젝트와 올바르게 매칭하지 못할 수 있습니다. 예를 들어 원격이 git@gitlab.com:group/project.git 대신 git@my-work-gitlab:group/project.git을 사용하는 경우입니다.

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

• 원격을 HTTP를 사용하도록 변경하거나 커스텀 별칭 없이 SSH를 사용합니다.
• GitLab 사용자 환경설정에서 기본 GitLab Duo 네임스페이스를 설정합니다.

HTTPS 프로젝트 클론은 되지만 SSH 클론은 실패하는 경우#

HTTPS 클론은 되는데 SSH 클론 오류가 발생할 수 있습니다. 이는 SSH URL의 호스트나 경로가 HTTPS 경로와 다를 때 발생합니다.

GitLab for VS Code 확장 프로그램은 다음을 사용합니다.

• 설정한 계정을 매칭하기 위한 호스트.
• 네임스페이스와 프로젝트 이름을 가져오기 위한 경로.

예를 들어 VS Code 확장 프로그램 프로젝트의 URL은 다음과 같습니다.

• SSH: git@gitlab.com:gitlab-org/gitlab-vscode-extension.git
• HTTPS: https://gitlab.com/gitlab-org/gitlab-vscode-extension.git

두 URL 모두 gitlab.com 호스트와 gitlab-org/gitlab-vscode-extension 경로를 갖습니다.

이 오류를 해결하려면:

1. SSH URL 이 다른 호스트를 사용하는지, 경로에 추가 세그먼트가 있는지 확인합니다.
2. 둘 중 하나라도 해당하면 Git 리포지터리를 GitLab 프로젝트에 수동으로 할당합니다.
   1. VS Code 왼쪽 사이드바에서 GitLab ([tanuki])을 선택합니다.
   2. (no GitLab project)로 표시된 프로젝트를 선택한 다음 Manually assign GitLab project를 선택합니다.
   3. 목록에서 올바른 프로젝트를 선택합니다.

이 과정을 간소화하는 방법에 대한 자세한 내용은 gitlab-vscode-extension 프로젝트의 이슈 577을 참고합니다.

네트워크 및 연결#

다음과 같은 네트워크 및 연결 오류가 발생할 수 있습니다.

프록시 사용 시 407 Access Denied 오류#

인증이 필요한 프록시를 사용하면 407 Access Denied (authentication_failed) 오류가 발생할 수 있습니다.

예를 들면 다음과 같습니다.

Request failed: Can't add GitLab account for https://gitlab.com. Check your instance URL and network connection.
Fetching resource from https://gitlab.com/api/v4/personal_access_tokens/self failed

이 오류를 해결하려면 GitLab Language Server에서 프록시 인증을 활성화합니다.

커스텀 인증서 관련 오류#

자체 서명 인증서와 같은 커스텀 인증서를 사용해 GitLab 인스턴스에 연결하면 오류가 발생할 수 있습니다.

인증서가 다음 설정을 사용하면 이러한 오류가 발생할 수 있습니다.

해결 방법은 Custom Certificate Authorities 용 확장 프로그램 설정을 참고합니다.

만료된 SSL 인증서#

실제로는 만료되지 않았는데 SSL 인증서가 만료됐다는 잘못된 오류가 발생할 수 있습니다. 예를 들면 다음과 같습니다.

API request failed - Error: certificate has expired.

이 오류를 해결하려면 시스템 인증서를 비활성화합니다.

1. VS Code에서 Settings 편집기를 엽니다.
   • macOS는 Code > Preferences > Settings를 선택합니다.
   • Windows 또는 Linux는 File > Preferences > Settings를 선택합니다
2. User 설정 탭에서 Application > Proxy를 선택합니다.
3. Proxy Strict SSL과 System Certificates 설정을 비활성화합니다.

도달할 수 없는 localhost 포트#

데스크톱이든 브라우저든 VS Code에서 GitLab Duo Agent Platform을 사용하면 다음과 같은 오류가 발생할 수 있습니다.

GitLab could not reach a service running on localhost:<unreachable_port> that this view depends on.

이 문제의 원인과 해결 방법은 VS Code를 데스크톱에서 사용하는지 브라우저에서 사용하는지에 따라 달라집니다.

데스크톱 환경#

GitLab Language Server는 VS Code에서 GitLab Duo Agent Platform UI를 렌더링하기 위해 localhost 포트에서 HTTP 서버를 실행합니다. 이 서버는 다음과 같은 VS Code 데스크톱 기반 원격 개발 환경에서 문제를 일으킬 수 있습니다.

• Remote-SSH: SSH를 통해 원격 머신(예: 클라우드 VM 또는 서버)에 연결할 수 있게 해주는 VS Code 기능입니다.
• Dev Containers: Docker 컨테이너 내부에서 개발 환경을 실행하는 VS Code 기능(이자 개방형 표준)입니다.
• Windows Subsystem for Linux (WSL): Windows에서 Linux 환경을 직접 실행하는 Windows 기능입니다.

이 문제는 Language Server의 웹뷰 포트가 VS Code UI 렌더링 컨텍스트에서 도달 가능하다고 보장되지 않기 때문에 이러한 원격 개발 환경에서 발생합니다.

이 문제를 해결하려면:

1. Ports 패널을 열려면 View > Open View... > Ports를 선택합니다.

2. 오류 메시지에 있는 포트를 찾아서 열거나 포트를 직접 입력합니다.

   포트 옆의 녹색 점이 연결이 작동함을 보장하지는 않습니다. 확인하려면 GitLab Duo Agent Platform 뷰를 다시 엽니다.

3. 포트를 열 수 없다면 방화벽, VPN, 백신 설정이 포트를 차단하고 있을 수 있습니다. 해당 설정을 확인한 다음 뷰를 다시 엽니다.

브라우저 환경#

이 문제를 해결하는 방법은 브라우저 기반 VS Code 환경이 이런 유형의 localhost 포트 포워딩을 지원하는지에 따라 달라집니다.

• 환경이 이런 유형의 localhost 포트 포워딩을 지원하고 Ports 패널을 사용할 수 있다면 View > Open View... > Ports를 선택합니다. 오류 메시지에 있는 차단된 포트를 찾아서 엽니다.
• 환경이 이런 유형의 localhost 포트 포워딩을 지원하지 않으면 이 웹뷰는 작동하지 않습니다. 대신 동일한 워크스페이스에 연결된 VS Code 데스크톱 애플리케이션을 사용합니다.

GitLab Duo#

VS Code에서 GitLab Duo를 사용하면 다음과 같은 문제가 발생할 수 있습니다.

GitLab Duo 기능을 사용할 수 없는 경우#

VS Code에서 GitLab Duo 오류를 해결하려면:

1. 사전 요구 사항을 충족하는지, 필요한 설정이 켜져 있는지 확인합니다.
2. Admin mode가 비활성화되어 있는지 확인합니다.
3. 진단 출력을 확인합니다.
   1. VS Code에서 View > Command Palette를 선택합니다.
   2. GitLab: Diagnostics 명령을 실행하고 실패한 검사가 있는지 출력을 확인합니다.
4. 진단 결과 해당 기능이 켜져 있지 않다면:
   1. VS Code에서 Settings 편집기를 엽니다.
      • macOS는 Code > Preferences > Settings를 선택합니다.
      • Windows 또는 Linux는 File > Preferences > Settings를 선택합니다
   2. Extensions > GitLab > GitLab Duo를 선택합니다.
   3. 누락된 기능에 해당하는 GitLab › 섹션을 찾아 체크박스를 선택해 켭니다.
5. 진단 결과 현재 프로젝트에서 Agentic Chat 이 지원되지 않는다고 나오면 기본 GitLab Duo 네임스페이스를 설정합니다.
6. 진단 결과 모든 Agentic Chat 검사를 통과했는데도 패널이 보이지 않는다면 커스텀 VS Code 레이아웃에 가려져 있을 수 있습니다.
   1. VS Code에서 View > Command Palette를 선택합니다.
   2. View: Show GitLab Duo Agent Platform 또는 View: Toggle GitLab Duo Agent Platform 명령을 실행합니다.

Code Suggestions 관련 지원은 Code Suggestions 문제 해결을 참고합니다.

GitLab Duo가 WebSocket 엔드포인트 대신 HTTP/1.1 응답을 반환하는 경우#

로그에서 GitLab Duo가 /-/cable WebSocket 엔드포인트 대신 HTTP/1.1 응답을 반환하는 것을 볼 수 있습니다.

이는 GitLab 인스턴스가 WebSocket 연결을 차단할 때 발생합니다.

이 오류를 해결하려면 네트워크 관리자에게 GitLab 인스턴스가 IDE 클라이언트로부터의 인바운드 WebSocket 연결을 허용하도록 수정해 달라고 요청합니다.

GitLab Duo Agent Platform 연결이 WebSocket 오류 1006 또는 404로 실패하면 WebSocket 오류 1006 또는 404로 연결 실패를 참고합니다.

원격 환경에서 GitLab Duo Chat 초기화가 실패하는 경우#

원격 개발 환경(브라우저 기반 VS Code 또는 원격 SSH 연결 등)에서 GitLab Duo Chat을 사용하면 다음과 같은 초기화 실패가 발생할 수 있습니다.

• 빈 화면이거나 로딩되지 않는 Chat 패널.
• The webview didn't initialize in 10000ms와 같은 로그 오류.
• 확장 프로그램이 접근할 수 없는 로컬 URL에 연결을 시도.

이 오류를 해결하려면:

1. VS Code에서 Settings 편집기를 엽니다.

   • macOS는 Code > Preferences > Settings를 선택합니다.
   • Windows 또는 Linux는 File > Preferences > Settings를 선택합니다

2. 오른쪽 위 모서리에서 **Open Settings (JSON)**을 선택해 settings.json 파일을 편집합니다.

3. 다음 설정을 추가하거나 수정합니다.

   "gitlab.featureFlags.languageServerWebviews": false
   

4. 변경 사항을 저장하고 창을 새로고침합니다.

   1. VS Code에서 View > Command Palette를 선택합니다.
   2. Developer: Reload Window를 입력하고 Enter를 누릅니다.

영구적인 해결책에 대한 최신 소식은 이슈 #1944와 이슈 #1943을 참고합니다.

GitLab Duo 명령이 실패하거나 무한히 실행되는 경우#

IDE에서 GitLab Duo Agentic Chat 이나 Software Development Flow를 사용하면 GitLab Duo가 루프에 갇히거나 명령 실행에 어려움을 겪을 수 있습니다.

이 문제는 Oh My ZSH! 나 powerlevel10k 같은 셸 테마나 통합을 사용할 때 발생할 수 있습니다. GitLab Duo 에이전트가 터미널을 생성할 때 셸 테마나 통합이 명령이 제대로 실행되는 것을 방해할 수 있습니다.

우회 방법으로 아래 안내를 따라 에이전트가 보낸 명령에는 더 단순한 테마를 사용합니다.

수정에 대한 자세한 내용은 이슈 2116을 참고합니다.

.zshrc 파일 편집#

VS Code에서 에이전트가 보낸 명령을 실행할 때 Oh My ZSH! 나 powerlevel10k가 더 단순한 테마를 사용하도록 설정합니다. IDE가 노출하는 환경 변수를 사용해 이 값을 설정할 수 있습니다.

다음 코드를 포함하도록 ~/.zshrc 파일을 편집합니다.

# ~/.zshrc

# Path to your oh-my-zsh installation
export ZSH="$HOME/.oh-my-zsh"

# ...

# Decide whether to load a full terminal environment,
# or keep it minimal for agentic AI in IDEs
if [[ "$TERM_PROGRAM" == "vscode" ]]; then
  echo "IDE agentic environment detected, not loading full shell integrations"
else
  # Oh My ZSH
  source $ZSH/oh-my-zsh.sh
  # Theme: Powerlevel10k
  [[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh
  # Other integrations like syntax highlighting
fi

# Other setup, like PATH variables

Bash 셸 편집#

VS Code에서 Bash의 고급 프롬프트를 끌 수 있습니다.

다음 코드를 포함하도록 ~/.bashrc 또는 ~/.bash_profile 파일을 편집합니다.

# ~/.bashrc or ~/.bash_profile

# Decide whether to load a full terminal environment,
# or keep it minimal for Agentic AI in IDEs
if [[ "$TERM_PROGRAM" == "vscode" ]]; then
  echo "IDE agentic environment detected, not loading full shell integrations"

  # Keep only essential settings for agents
  export PS1='\$ '  # Minimal prompt

else
  # Load full Bash environment

  # Custom prompt (e.g., Starship, custom PS1)
  if command -v starship &> /dev/null; then
    eval "$(starship init bash)"
  else
    # ... Add your own PS1 variable
  fi

  # Load additional integrations
fi

# Always load essential environment variables and aliases

지원에 필요한 정보#

지원팀에 문의하기 전에 최신 버전의 GitLab for VS Code 확장 프로그램이 설치되어 있는지 확인합니다.

최신 릴리스는 VS Code Marketplace의 Version History 탭에서 확인할 수 있습니다.

영향을 받은 사용자로부터 다음 정보를 수집해 버그 신고서에 제공합니다.

1. 사용자에게 표시된 오류 메시지.
2. GitLab 및 GitLab Language Server 로그.
3. 진단 출력.
   1. VS Code에서 View > Command Palette를 선택합니다.
   2. GitLab: Diagnostics를 입력하고 Enter를 누릅니다.
   3. 확장 프로그램 버전을 기록합니다.
4. 시스템 세부 정보:
   • VS Code의 OS 세부 정보:
     • macOS는 Code > About Visual Studio Code로 이동해 OS를 확인합니다.
     • Windows 또는 Linux는 Help > About으로 이동해 OS를 확인합니다.
   • 머신 사양(CPU, RAM): IDE에서는 확인할 수 없으므로 사용 중인 머신에서 직접 제공합니다.
5. 영향받는 사용자 수를 포함해 영향 범위를 설명합니다.
6. 오류를 재현하는 방법을 설명합니다. 가능하면 화면 녹화를 포함합니다.
7. 다른 GitLab Duo 기능이 어떤 영향을 받는지 설명합니다.
   • GitLab Quick Chat 이 정상적으로 작동하는지 여부.
   • Code Suggestions가 작동하는지 여부.
   • Web IDE의 GitLab Duo Chat 이 응답을 반환하는지 여부.
8. GitLab for VS Code 확장 프로그램 격리 가이드에 설명된 대로 확장 프로그램 격리 테스트를 수행합니다. 다른 확장 프로그램이 문제를 일으키는지 확인하기 위해 다른 모든 확장 프로그램을 비활성화(또는 제거)해 봅니다.