Skip to content

Latest commit

 

History

History
121 lines (77 loc) · 6.1 KB

netconfig.md

File metadata and controls

121 lines (77 loc) · 6.1 KB
Raw

Network and HTTP configuration

Git Credential Manager Core's network and HTTP(S) behavior can be configured in a few different ways via environment variables and configuration options.

HTTP Proxy

If your computer sits behind a network firewall that requires the use of a proxy server to reach repository remotes or the wider Internet, there are various methods for configuring GCM to use a proxy.

The simplest way to configure a proxy for all HTTP(S) remotes is to use the standard Git HTTP(S) proxy setting http.proxy.

For example to configure a proxy for all remotes for the current user:

git config --global http.proxy http://proxy.example.com

To specify a proxy for a particular remote you can use the remote.<name>.proxy repository-level setting, for example:

git config --local remote.origin.proxy http://proxy.example.com

The advantage to using these standard configuration options is that in addition to GCM being configured to use the proxy, Git itself will be configured at the same time. This is probably the most commonly desired case in environments behind an Internet-blocking firewall.

Authenticated proxies

Some proxy servers do not accept anonymous connections and require authentication. In order to specify the credentials to be used with a proxy, you can specify the username and password as part of the proxy URL setting.

The format follows RFC 3986 section 3.2.1 by including the credentials in the 'user information' part of the URI. The password is optional.

protocol://username[:password]@hostname

For example, to specify the username john.doe and the password letmein123 for the proxy server proxy.example.com:

https://john.doe:[email protected]

If you have special characters (as defined by RFC 3986 section 2.2) in your username or password such as :, @, or any other non-URL friendly character you can URL-encode them (section 2.1).

For example, a space character would be encoded with %20.

Other proxy options

GCM Core supports other ways of configuring a proxy for convenience and compatibility.

  1. GCM-specific configuration options (only respected by GCM; deprecated):
    • credential.httpProxy
    • credential.httpsProxy
  2. cURL environment variables (also respected by Git):
    • HTTP_PROXY
    • HTTPS_PROXY
    • ALL_PROXY
  3. GCM_HTTP_PROXY environment variable (only respected by GCM; deprecated)

Bypassing addresses

In some circumstances you may wish to bypass a configured proxy for specific addresses. GCM Core supports the cURL environment variable NO_PROXY for this scenariom, as does Git itself.

The NO_PROXY environment variable should contain a comma (,) or space ( ) separated list of regular expressions to match hosts that should not be proxied (should connect directly).

Example:

NO_PROXY="contoso.com,www.fabrikam.com"

TLS Verification

If you are using self-signed TLS (SSL) certificates with a self-hosted host provider such as GitHub Enterprise Server or Azure DevOps Server (previously TFS), you may see the following error message when attempting to connect using Git and/or GCM:

$ git clone https://ghe.example.com/john.doe/myrepo
fatal: The remote certificate is invalid according to the validation procedure.

The recommended and safest option is to acquire a TLS certificate signed by a public trusted certificate authority (CA). There are multiple public CAs; here is a non-exhaustive list to consider: Let's Encrypt, Comodo, Digicert, GoDaddy, GlobalSign.

If it is not possible to obtain a TLS certificate from a trusted 3rd party then you should try to add the specific self-signed certificate or one of the CA certificates in the verification chain to your operating system's trusted certificate store (macOS, Windows).

If you are unable to either obtain a trusted certificate, or trust the self-signed certificate you can disable certificate verification in Git and GCM.

Security Warning ⚠️

Disabling verification of TLS (SSL) certificates removes protection against a man-in-the-middle (MITM) attack.

Only disable certificate verification if you are sure you need to, are aware of all the risks, and are unable to trust specific self-signed certificates (as described above).

The environment variable GIT_SSL_NO_VERIFY and Git configuration option http.sslVerify can be used to control TLS (SSL) certificate verification.

To disable verification for a specific remote (for example https://example.com):

git config --global http.https://example.com.sslVerify false

To disable verification for the current user for all remotes (not recommended):

# Environment variable (Windows)
SET GIT_SSL_NO_VERIFY=1

# Environment variable (macOS/Linux)
export GIT_SSL_NO_VERIFY=1

# Git configuration (Windows/macOS/Linux)
git config --global http.sslVerify false

Note: You may also experience similar verification errors if you are using a network traffic inspection tool such as Telerik Fiddler. If you are using such tools please consult their documentation for trusting the proxy root certificates.