doc/editor_extensions/visual_studio_code/ssl.md
You can use the GitLab for VS Code extension even if your GitLab instance uses either a custom or self-signed SSL certificate.
In controlled enterprise environments, organizations often use custom certificate authorities (CA). The GitLab for VS Code extension must trust these certificates to communicate with your GitLab instance.
You must download the complete certificate chain. This includes:
Contact your IT or security team and request either of the following:
Instead of contacting your IT or security team, you can export the complete certificate chain from your browser:
{{< tabs >}}
{{< tab title="Google Chrome & Microsoft Edge" >}}
{{< /tab >}}
{{< tab title="Firefox" >}}
{{< /tab >}}
{{< /tabs >}}
You can configure the custom certificate in multiple ways.
If your organization installs trusted certificate authorities at the operating system level, the GitLab for VS Code extension automatically trusts these certificate authorities through the underlying Node.js and VS Code runtime.
This works well in:
Prerequisites:
gitlab.ca VS Code setting is not in use.You do not have to configure any other GitLab extension settings in this scenario.
Prerequisites:
Have a certificate bundle file in PEM format, with the full certificate chain. Every certificate must be concatenated in order from root to intermediate:
-----BEGIN CERTIFICATE-----
[Root CA Certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate CA Certificate]
-----END CERTIFICATE-----
Open VS Code.
Open the Command Palette:
Type "Preferences: Open User Settings (JSON)" and select it. The settings.json file opens.
Add the gitlab.ca setting with the absolute path to your certificate bundle
file, replacing the example path with the actual path to your certificate file:
{{< tabs >}}
{{< tab title="macOS and Linux" >}}
{
"gitlab.ca": "/etc/ssl/certs/ca-bundle.pem"
}
{{< /tab >}}
{{< tab title="Windows" >}}
{
"gitlab.ca": "C:\\certs\\ca-bundle.pem"
}
{{< /tab >}}
{{< /tabs >}}
Save the file.
Reload VS Code for the changes to take effect.
[!warning] Disabling certificate verification is a security risk. Only disable verification for testing or development.
Open VS Code.
Open the Command Palette:
Type "Preferences: Open User Settings (JSON)" and select it. The settings.json file opens.
Add the following setting:
{
"gitlab.ignoreCertificateErrors": true
}
Save the file.
Reload VS Code for the changes to take effect.
Prerequisites:
gitlab.ca VS Code setting is not in use.[!note] If you also use a proxy to connect to your GitLab instance, add a comment to issue 314. If you still have connection problems after completing these steps, review epic 6244, which links to all existing SSL issues for the GitLab for VS Code extension.
To use a self-signed SSL certificate:
Ensure your CA certificate is correctly added to your system for the extension to work. VS Code reads
the system certificate store, and changes all node http requests to trust the certificates:
%%{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]
The GitLab instance certificate's CA must be explicitly specified as a trusted CA. If intermediate certificates are in use, these must be available on the system. If the entire chain does not validate successfully, network connections within the extension fail to authenticate.
For more information, see Self-signed certificate error when installing Python support in WSL in the Visual Studio Code issue tracker.
In your VS Code settings.json, set "http.systemCertificates": true. The default value is true, so you might not need to change this value.
Complete the instructions in the following sections for your operating system.
[!note] These instructions were tested on Windows 10 and VS Code 1.60.0.
Make sure you can see your self-signed CA in your certificate store:
certmgr.[!note] These instructions were tested on Arch Linux
5.14.3-arch1-1and VS Code 1.60.0.
update-ca-trust (Fedora, RHEL, CentOS)update-ca-certificates (Ubuntu, Debian, OpenSUSE, SLES)trust (Arch)/etc/ssl/certs/ca-certificates.crt or /etc/ssl/certs/ca-bundle.crt.
VS Code checks this location.[!note] These instructions were tested on macOS Tahoe 26, VS Code 1.101.2, and GitLab for VS Code 6.51.1.
Make sure you see the self-signed CA in your keychain:
When working with custom and self-signed certificates in the VS Code extension, you might encounter the following issues.
You might get an error that states "...unable to verify the first certificate".
This issue occurs when there are missing intermediate certificates in the chain.
To resolve this:
You might get an error that states "...self signed certificate in certificate chain".
This issue occurs when VS Code does not trust your organization's root CA.
To resolve this, do either of the following:
You might get an error that states "...certificate has expired".
This issue occurs when one or more certificates in the chain have expired.
To resolve this:
openssl x509 -in certificate.pem -noout -dates.If you continue experiencing issues, try the following.
Open the Command Palette:
Type "Preferences: Open User Settings (JSON)" and select that option. The settings.json file opens.
Add the following to settings.json to enable detailed logging:
{
"gitlab.debug": true
}
To view the logs, in the Command Palette, type "GitLab: Show Extension Logs" and select it.
Look for certificate errors in the logs.
Test the connection with the custom CA:
curl --cacert /path/to/ca-bundle.pem "https://gitlab.example.com"
Check the certificate details:
openssl x509 -in ca-bundle.pem -text -noout
Verify the certificate chain, replacing server-cert.pem with your server's
certificate:
openssl verify -CAfile ca-bundle.pem server-cert.pem
#vscode-extension channel