Skip to content

Latest commit

 

History

History
176 lines (122 loc) · 8 KB

netconfig.md

File metadata and controls

176 lines (122 loc) · 8 KB
Raw

Network and HTTP configuration

Git Credential Manager'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:letmein123@proxy.example.com

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 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/HTTPS_PROXY
    • all_proxy/ALL_PROXY
  3. GCM_HTTP_PROXY environment variable (only respected by GCM; deprecated)

Note that with the cURL environment variables there are both lowercase and uppercase variants.

Lowercase variants take precedence over the uppercase form. This is consistent with how libcurl (and therefore Git) operates.

The http_proxy variable exists only in the lowercase variant and libcurl does not consider any uppercase form. GCM also reflects this behavior.

See the curl docs for more information.

Bypassing addresses

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

Like with the other cURL proxy environment variables, the lowercase variant will take precedence over the uppercase form.

This environment variable should contain a comma-separated or space-separated list of host names that should not be proxied (should connect directly).

GCM attempts to match libcurl's behaviour, which is briefly summarized here:

  • a value of * disables proxying for all hosts;
  • other wildcard use is not supported;
  • each name in the list is matched as a domain which contains the hostname, or the hostname itself
  • a leading period/dot . matches against the provided hostname

For example, setting NO_PROXY to example.com results in the following:

Hostname Matches?
example.com ✅
example.com:80 ✅
www.example.com ✅
notanexample.com ❌
www.notanexample.com ❌
example.com.othertld ❌

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.