GitLab 인스턴스에서 사용자 지정 SSL 인증서나 자체 서명 SSL 인증서를 사용하더라도 GitLab for VS Code 확장 프로그램을 사용할 수 있습니다.

사용자 지정 인증서 사용#

통제된 엔터프라이즈 환경에서는 조직이 사용자 지정 인증 기관(CA)을 사용하는 경우가 많습니다. GitLab 인스턴스와 통신하려면 GitLab for VS Code 확장 프로그램이 이러한 인증서를 신뢰해야 합니다.

전체 인증서 체인 다운로드#

전체 인증서 체인을 다운로드해야 합니다. 여기에는 다음이 포함됩니다:

• 루트 CA 인증서.

• 모든 중간 CA 인증서.

• 선택 사항. 서버 인증서(일반적으로 자동으로 다운로드됨).

IT 팀 또는 보안 팀에 문의하여 다음 중 하나를 요청하세요:

• PEM 형식의 전체 인증서 체인.

• 개별 루트 및 중간 CA 인증서.

전체 인증서 체인 내보내기#

IT 팀이나 보안 팀에 문의하는 대신, 브라우저에서 전체 인증서 체인을 내보낼 수 있습니다:

Google Chrome & Microsoft Edge

• GitLab 인스턴스로 이동합니다.

• 주소 표시줄에서 자물쇠 아이콘을 선택합니다.

• Connection is secure > Certificate is valid를 선택합니다.

• Certification Path 탭으로 이동합니다.

• 루트부터 시작하여 체인의 각 인증서를 내보냅니다.

  Firefox

• GitLab 인스턴스로 이동합니다.

• 주소 표시줄에서 자물쇠 아이콘을 선택합니다.

• Connection secure > More information을 선택합니다.

• View Certificate를 선택합니다.

• 체인의 각 인증서를 PEM 형식으로 다운로드합니다.

사용자 지정 인증서 구성#

사용자 지정 인증서는 여러 가지 방법으로 구성할 수 있습니다.

시스템 인증서 저장소 사용#

조직이 운영 체제 수준에서 신뢰할 수 있는 인증 기관을 설치하는 경우, GitLab for VS Code 확장 프로그램은 기반이 되는 Node.js 및 VS Code 런타임을 통해 이러한 인증 기관을 자동으로 신뢰합니다.

이 방법은 다음 환경에서 잘 작동합니다:

• 루트 및 중간 인증 기관이 사전 설치된 회사 관리 기기.

• 사용자 지정 CA 구성 없이도 다른 HTTPS 도구가 이미 작동하는 환경.

사전 요구 사항:

• GitLab Workflow 확장 프로그램 버전 6.51.1 이상.

• VS Code 버전 1.101.2 이상.

• gitlab.ca VS Code 설정이 사용 중이 아니어야 합니다.

이 시나리오에서는 다른 GitLab 확장 프로그램 설정을 구성할 필요가 없습니다.

사용자 지정 인증서 파일 지정#

사전 요구 사항:

전체 인증서 체인이 포함된 PEM 형식의 인증서 번들 파일이 있어야 합니다. 모든 인증서는 루트에서 중간 순서대로 연결되어 있어야 합니다:

-----BEGIN CERTIFICATE-----
[Root CA Certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate CA Certificate]
-----END CERTIFICATE-----

VS Code를 엽니다.

명령 팔레트를 엽니다:

Windows 및 Linux: Control+Shift+P.

• macOS: Command+Shift+P.

"Preferences: Open User Settings (JSON)"을 입력하고 선택합니다. settings.json 파일이 열립니다.

인증서 번들 파일의 절대 경로를 지정하여 gitlab.ca 설정을 추가하고, 예시 경로를 실제 인증서 파일 경로로 바꿉니다:

macOS 및 Linux

     {
      "gitlab.ca": "/etc/ssl/certs/ca-bundle.pem"
     }

Windows

    {
     "gitlab.ca": "C:\\certs\\ca-bundle.pem"
    }

파일을 저장합니다.

변경 사항을 적용하려면 VS Code를 다시 로드합니다.

인증서 확인 비활성화#

인증서 확인을 비활성화하는 것은 보안 위험입니다. 테스트 또는 개발 목적으로만 확인을 비활성화하세요.

- VS Code를 엽니다.

명령 팔레트를 엽니다:

Windows 및 Linux: Control+Shift+P.

• macOS: Command+Shift+P.

"Preferences: Open User Settings (JSON)"을 입력하고 선택합니다. settings.json 파일이 열립니다.

다음 설정을 추가합니다:

{
  "gitlab.ignoreCertificateErrors": true
}

파일을 저장합니다.

변경 사항을 적용하려면 VS Code를 다시 로드합니다.

자체 서명 SSL 인증서 사용#

사전 요구 사항:

• GitLab 인스턴스가 자체 서명 인증 기관(CA)으로 서명된 인증서를 사용해야 합니다.

• GitLab for VS Code 버전 6.51.1 이상.

• VS Code 버전 1.101.2 이상.

• gitlab.ca VS Code 설정이 사용 중이 아니어야 합니다.

  프록시를 통해 GitLab 인스턴스에 연결하는 경우, 이슈 314에 댓글을 남겨 주세요. 이 단계를 완료한 후에도 연결 문제가 지속된다면, GitLab for VS Code 확장 프로그램의 모든 기존 SSL 이슈가 연결된 에픽 6244를 검토하세요.

  자체 서명 SSL 인증서를 사용하려면:

확장 프로그램이 작동하려면 CA 인증서가 시스템에 올바르게 추가되어 있어야 합니다. VS Code는 시스템 인증서 저장소를 읽고, 모든 node http 요청이 해당 인증서를 신뢰하도록 변경합니다:

%%{init: { "fontFamily": "GitLab Sans" }}%% graph LR accTitle: Self-signed certificate chain accDescr: Shows a self-signed CA that signs the GitLab instance certificate.

A[Self-signed CA] -- signed --> B[Your GitLab instance certificate]

GitLab 인스턴스 인증서의 CA는 명시적으로 신뢰할 수 있는 CA로 지정되어야 합니다. 중간 인증서가 사용 중인 경우, 해당 인증서가 시스템에서 사용 가능해야 합니다. 전체 체인이 성공적으로 유효성 검사되지 않으면, 확장 프로그램 내의 네트워크 연결이 인증에 실패합니다.

자세한 내용은 Visual Studio Code 이슈 트래커의 WSL에서 Python 지원 설치 시 자체 서명 인증서 오류를 참조하세요.

VS Code의 settings.json에서 "http.systemCertificates": true로 설정하세요. 기본값이 true이므로 이 값을 변경하지 않아도 될 수 있습니다.

다음 섹션의 운영 체제별 지침을 완료하세요.

Windows#

이 지침은 Windows 10 및 VS Code 1.60.0에서 테스트되었습니다.

인증서 저장소에서 자체 서명 CA를 볼 수 있는지 확인하세요:

• 명령 프롬프트를 엽니다.

• certmgr을 실행합니다.

• 신뢰할 수 있는 루트 인증 기관 > 인증서에서 인증서가 표시되는지 확인합니다.

Linux#

이 지침은 Arch Linux `5.14.3-arch1-1` 및 VS Code 1.60.0에서 테스트되었습니다.

• 운영 체제의 도구를 사용하여 자체 서명 CA를 시스템에 추가할 수 있는지 확인하세요:

update-ca-trust (Fedora, RHEL, CentOS)

• update-ca-certificates (Ubuntu, Debian, OpenSUSE, SLES)

• trust (Arch)

• CA 인증서가 /etc/ssl/certs/ca-certificates.crt 또는 /etc/ssl/certs/ca-bundle.crt에 있는지 확인하세요. VS Code는 이 위치를 확인합니다.

MacOS#

이 지침은 macOS Tahoe 26, VS Code 1.101.2, GitLab for VS Code 6.51.1에서 테스트되었습니다.

키체인에서 자체 서명 CA를 볼 수 있는지 확인하세요:

• Finder > 응용 프로그램 > 유틸리티 > 키체인 접근으로 이동합니다.

• 왼쪽 열에서 시스템을 선택합니다.

• 목록에서 자체 서명 CA 인증서를 찾습니다.

• 인증서를 마우스 오른쪽 버튼으로 클릭하고 정보 가져오기를 선택합니다.

• 신뢰 섹션을 펼칩니다.

• Secure Sockets Layer (SSL) 옵션이 '항상 신뢰'로 설정되어 있는지 확인합니다.

관련 주제#

• VS Code 네트워크 설정

• OpenSSL 문서

• GitLab SSL 구성

트러블슈팅#

VS Code 확장 프로그램에서 사용자 지정 인증서 및 자체 서명 인증서를 사용할 때 다음과 같은 이슈가 발생할 수 있습니다.

오류: "…unable to verify the first certificate"#

"…unable to verify the first certificate"라는 오류가 발생할 수 있습니다.

이 이슈는 체인에 중간 인증서가 누락된 경우에 발생합니다.

이 이슈를 해결하려면:

• 전체 인증서 체인이 있는지 확인합니다.

• 모든 인증서가 PEM 형식인지 확인합니다.

• 인증서가 올바른 순서(루트 > 중간 > 리프)로 연결되어 있는지 확인합니다.

오류: "…self signed certificate in certificate chain"#

"…self signed certificate in certificate chain"이라는 오류가 발생할 수 있습니다.

이 이슈는 VS Code가 조직의 루트 CA를 신뢰하지 않는 경우에 발생합니다.

이 이슈를 해결하려면 다음 중 하나를 수행합니다:

• 루트 CA를 인증서 번들에 추가합니다.

• CA가 시스템 전체에 설치되어 있는 경우 시스템 인증서 저장소를 활성화합니다.

오류: "…certificate has expired"#

"…certificate has expired"라는 오류가 발생할 수 있습니다.

이 이슈는 체인의 인증서 중 하나 이상이 만료된 경우에 발생합니다.

이 이슈를 해결하려면:

• IT 팀 또는 보안 팀에 업데이트된 인증서를 요청합니다.

• openssl x509 -in certificate.pem -noout -dates를 실행하여 인증서 만료 날짜를 확인합니다.

일반적인 트러블슈팅 단계#

이슈가 계속 발생하면 다음을 시도해 보세요.

확장 프로그램 로그 확인#

명령 팔레트를 엽니다:

Windows 및 Linux: Control+Shift+P.

• macOS: Command+Shift+P.

"Preferences: Open User Settings (JSON)"을 입력하고 해당 옵션을 선택합니다. settings.json 파일이 열립니다.

상세 로깅을 활성화하려면 settings.json에 다음을 추가합니다:

{
  "gitlab.debug": true
}

로그를 보려면 명령 팔레트에서 "GitLab: Show Extension Logs"를 입력하고 선택합니다.

로그에서 인증서 오류를 찾습니다.

인증서 체인 구성 확인#

사용자 지정 CA로 연결을 테스트합니다:

curl --cacert /path/to/ca-bundle.pem "https://gitlab.example.com"

인증서 세부 정보를 확인합니다:

openssl x509 -in ca-bundle.pem -text -noout

server-cert.pem을 사용 중인 서버의 인증서로 바꾸어 인증서 체인을 확인합니다:

openssl verify -CAfile ca-bundle.pem server-cert.pem

지원 문의#

• GitLab 포럼

• GitLab Discord #vscode-extension 채널

• 이슈 등록

• GitLab 계정 팀에 문의합니다. 확장 프로그램 로그와 인증서 확인 출력을 포함하세요.