Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git: SSL certificate problem: self-signed certificate in certificate chain

The browser trusts it and Git does not. Identify the root, keep the public bundle, and avoid the global sslVerify setting that hides the problem.

~5 min readGit
#Git#TLS#Proxy#CI
A certificate chain of three plates with the top root broken away in amber and a cyan trust key

Introduction & Quick Summary

Symptom. Every remote operation fails at once, on a network that is otherwise fine:

code
fatal: unable to access 'https://github.com/acme/api.git/': SSL certificate problem: self-signed certificate in certificate chain

The browser opens the same URL without complaint. git clone of a public repository fails too, so this is not about credentials or the remote. In WSL, a container or a CI runner the message can also appear as SSL certificate problem: unable to get local issuer certificate.

Cause. Git verifies the TLS chain with libcurl and its own CA bundle. Something in the chain is not in that bundle: a corporate TLS-inspection proxy that re-signs traffic with a private root, a self-hosted Git server that sends its private root, or endpoint security software that inserts a root into the local store (Schannel on Windows) but not into Git's bundle. Windows trusts the proxy through group policy, while Git for Windows, WSL, Docker images and CI runners do not.

Fix. Make Git trust the specific root, keeping the public roots in place:

bash
# inspect the chain and identify the top certificate openssl s_client -connect github.com:443 -servername github.com -showcerts </dev/null 2>/dev/null \ | grep -E '^\s*(0|1|2) s:|^\s*i:' # build a bundle that keeps the public roots and appends the corporate root cat /etc/ssl/certs/ca-certificates.crt corp-root.pem > ~/.config/git/ca-bundle.pem git config --global http.sslCAInfo ~/.config/git/ca-bundle.pem
cmd
:: Windows, when the root is already in the Windows store git config --global http.sslBackend schannel

http.sslVerify=false is a diagnostic for one command, never a fix.

Core Mechanics, Signatures & Reproducible Setup

Git's HTTPS transport is libcurl. Verification checks the server's chain against the bundle at http.sslCAInfo, or the backend's default store, and fails if any link is untrusted. Two consequences matter in practice: replacing the bundle with only the corporate root breaks every other host, and sslBackend schannel uses the operating system store instead of a file.

Reproduce the error locally with a self-signed certificate, which is the same failure the proxy produces:

bash
mkdir -p /tmp/tls && cd /tmp/tls openssl req -x509 -newkey rsa:2048 -nodes -days 1 \ -keyout key.pem -out cert.pem -subj "/CN=localhost" python3 - <<'PY' & import http.server, ssl s = http.server.HTTPServer(("localhost", 8443), http.server.SimpleHTTPRequestHandler) ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) ctx.load_cert_chain("cert.pem", "key.pem") s.socket = ctx.wrap_socket(s.socket, server_side=True) s.serve_forever() PY git ls-remote https://localhost:8443/repo.git # fatal: unable to access '...': SSL certificate problem: self-signed certificate
bash
# same operation, trusting the test root on purpose GIT_SSL_CAINFO=/tmp/tls/cert.pem git ls-remote https://localhost:8443/repo.git

GIT_SSL_CAINFO also shows how the setting reaches tools that shell out to Git, which is why it is the better variable to set in a build script than an edit to a user's global config.

Key Comparison Table

ConfigurationTrust store usedGood for
defaultGit's bundled ca-bundle.crtpublic hosts
http.sslCAInfothe named file, replacing the defaultone project or user with a corporate root
http.sslBackend schannelWindows certificate storemanaged Windows machines
http.sslBackend opensslfile bundle (default on Linux)explicit, repeatable CI
GIT_SSL_CAINFOfile for one process treebuild scripts, containers
http.sslVerify falsenonediagnosis only, never committed
http.proxy plus sslCAInfoproxy for transport, bundle for trustinspection proxies
Where the error appearsWho needs the root installed
git on Linuxca-certificates package plus update-ca-certificates
Git for WindowsWindows store via schannel, or a bundle file
WSLthe distributions's store, separately from Windows
Docker buildthe image's store, plus any tool that bundles its own
Node, Python, Go in the same jobNODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR
IDE Git integrationthe same user's Git config, or the IDE's own setting

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Install the root system-wide on Linux

One update-ca-certificates run fixes Git, curl, wget, pip and most other tools at once, which is the right move on a developer machine:

bash
sudo cp corp-root.pem /usr/local/share/ca-certificates/corp-root.crt sudo update-ca-certificates git ls-remote https://github.com/acme/api.git HEAD

On RHEL-family systems the equivalent is dropping the .pem into /etc/pki/ca-trust/source/anchors/ and running update-ca-trust. Container images need their own layer, because the host store is not mounted into the build.

2. The proxy root that changes with the egress path

Inspection proxies sometimes present different roots per network segment, so a configuration that works in the office fails on VPN and vice versa. Fetch the chain from the failing environment rather than copying a certificate from a wiki:

bash
openssl s_client -connect git.example.com:443 -servername git.example.com \ -showcerts </dev/null 2>/dev/null | awk '/BEGIN CERT/{n++} n==3,/END CERT/'

If the top certificate names a security vendor, the fix is to trust that vendor's root and to keep it updated, which is an infrastructure responsibility, not a per-developer one.

3. CI runners and build images

CI is where "it works on my machine" becomes a red pipeline. Two patterns work: install the root in the image build, or pass it as a file and point Git at it:

# GitHub Actions - name: Trust corporate root run: | sudo cp ci/corp-root.crt /usr/local/share/ca-certificates/corp-root.crt sudo update-ca-certificates - uses: actions/checkout@v4
dockerfile
# Dockerfile COPY corp-root.crt /usr/local/share/ca-certificates/corp-root.crt RUN update-ca-certificates

Tools that bundle their own store still need their own variable, which is a common follow-up failure: pip install or npm install inside the same job fails with a different message even though Git now works.

4. Submodules and LFS use the same transport

A repository that clones but cannot fetch submodules is the same failure one level down. The configuration applies per process, so a build that shells out with a scrubbed environment loses it:

bash
git -c http.sslCAInfo="$PWD/ci/corp-root.pem" submodule update --init --recursive
bash
# global for the CI user, which submodule invocations inherit git config --global http."https://git.example.com/".sslCAInfo "$PWD/ci/corp-root.pem"

The per-host form scopes the trust to one origin, which is safer than a global bundle in a shared runner.

5. Diagnosing without disabling verification

sslVerify=false hides the problem and keeps it hidden in whatever config file it lands in. If you need a temporary bypass for one command, keep it on the command line with -c, and confirm the diagnosis with GIT_CURL_VERBOSE first:

bash
GIT_CURL_VERBOSE=1 git -c http.sslVerify=false ls-remote https://git.example.com/team/app.git 2>&1 \ | grep -E "SSL certificate|subject:|issuer:"

The verbose output names the issuer of the offending certificate, which is the string to search for when hunting the root.

6. Reverting a bad bundle change

Replacing the default bundle with a corporate-only file breaks GitHub, PyPI and everything else. The recovery is to rebuild the bundle from the system store rather than to find the original file:

bash
git config --global --unset http.sslCAInfo git config --global --get-regexp '^http\.' # what is left sudo update-ca-certificates --fresh

On Windows, switching back to openssl after schannel has the same effect: git config --global http.sslBackend openssl restores file-based verification.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Setting http.sslVerify=false globally. It silently disables verification for every repository on the machine.
  • Replacing the CA bundle with the corporate root only. Public hosts then fail with the same error in reverse.
  • Installing the root in Windows and expecting WSL to see it. WSL has its own store.
  • Forgetting the second tool in the same pipeline. Node, Python and Go need their own CA variables.
  • Trusting a certificate you cannot identify. Confirm the issuer before adding a root to a store.
  • Committing a ca-bundle.pem into the repository. It goes stale and it is not a secret to distribute that way.
  • Copying a root by hand into /etc/ssl/certs without update-ca-certificates. The hash symlink is missing, so the store ignores it.
  • Assuming a proxy root never changes. Renewal date changes break verification again with no code change.

Check the TLS endpoint and headers with the curl command builder before and after the change, and keep the certificate paths and variables readable with the environment file inspector when the setting lives in CI configuration.

Reference: http.sslCAInfo and http.sslBackend in git-config, and curl's certificate verification notes.

Official references

primary documentation

The Git documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.