Ako vyriešiť problém so SSL certifikátom: Unable to get local issuer certificate v Git

Neexistuje žiadna významná zmena v roku 2026, ktorá by urobila starý obchádzajúci postup „vypnúť SSL verifikáciu“ dobrým riešením. Aktuálna dokumentácia Gitu stále predvolene nastavuje http.sslVerify na true a Git stále podporuje dôveru CA založenú na súboroch aj voliteľné TLS backendy, ako sú OpenSSL a Schannel. Trvalé riešenie spočíva v tom, že Gitu umožníte dôverovať správnej certifikačnej autorite, alebo v oprave neúplného reťazca certifikátov servera – nie v zakázaní verifikácie.

Chyba SSL certificate problem: unable to get local issuer certificate znamená, že knižnica TLS používaná Gitom nedokázala zostaviť dôveryhodný reťazec certifikátov od certifikátu servera k certifikačnej autorite, ktorej dôveruje. To sa môže stať, pretože lokálne úložisko CA neobsahuje vydávajúcu CA, firemný proxy na inšpekciu HTTPS znovu podpisuje prevádzku internou CA, Git číta nesprávny zväzok CA, alebo samospravovaný server Git nepredkladá požadované medzicertifikáty.

Typické zlyhanie Git HTTPS: vzdialený server je dosiahnuteľný, ale verifikácia reťazca certifikátov nemôže nájsť dôveryhodného vydavateľa.

Začnite najbezpečnejšou odpoveďou

Použite toto poradie:

1. Potvrďte, ktoré nastavenia SSL Gitu a TLS backend sú aktívne.
2. Rozhodnite, či chýbajúca dôvera patrí do úložiska dôvery operačného systému, alebo do zväzku CA Gitu.
3. Ak mnoho klientov zlyháva na rovnakom samohostovanom serveri, opravte reťazec certifikátov servera namiesto opravovania každého klienta.
4. Znovu otestujte so zapnutou SSL verifikáciou a odstráňte akékoľvek dočasné alebo zastarané konfiguračné obchádzky.

Aktuálna dokumentácia git-config definuje http.sslVerify, http.sslCAInfo, http.sslCAPath, http.sslBackend a špecifické správanie Schannel používané na Windows. Predvolená hodnota pre verifikáciu certifikátov zostáva zapnutá.

Spoľahlivá oprava spočíva v obnovení platného reťazca dôvery, nie v potlačení kontroly certifikátu.

Krok 1: Zistite, čo Git skutočne používa

Pred inštaláciou certifikátov alebo úpravou konfigurácie skontrolujte hodnoty a ich pôvod:

git --version
git config --show-origin --get http.sslVerify
git config --show-origin --get http.sslCAInfo
git config --show-origin --get http.sslBackend
git config --show-origin --get http.proxy
git config --show-origin --get http.proxySSLCAInfo

Ak príkaz nič nevypíše, táto možnosť môže jednoducho používať predvolené nastavenie Gitu alebo libcurl. --show-origin je dôležité, pretože hodnota môže pochádzať zo systémových, globálnych, lokálnych repozitárových alebo zahrnutých konfiguračných súborov. Oprava nesprávnej úrovne môže nechať účinné nastavenie nezmenené.

Skontrolujte tiež vzdialený server, ku ktorému sa skutočne pripájate:

git remote -v
git ls-remote https://git.example.com/team/repo.git

Ak Git zlyháva iba pre jeden firemný alebo súkromný hostiteľ, zatiaľ čo verejné HTTPS stránky fungujú, problém je pravdepodobne špecifický pre hostiteľa alebo konfiguráciu servera. Ak Git zlyháva pre mnoho nesúvisiacich HTTPS vzdialených serverov, najprv skontrolujte lokálnu inštaláciu Gitu, cestu k zväzku CA, proxy a konfiguráciu dôvery systému.

Nerobte z tohto svoj prvý príkaz

git config --global http.sslVerify false

Toto vypne verifikáciu certifikátu servera pre požiadavky Git HTTPS na globálnej úrovni používateľa. Môže to spôsobiť zmiznutie chyby, ale zároveň odstráni ochranu, ktorá overuje, či komunikujete so zamýšľaným serverom. Git zdokumentoval, že verifikácia je predvolene zapnutá z dobrého dôvodu.

Ak nájdete starú globálnu obchádzku, ktorá už nie je potrebná, obnovte predvolené správanie:

git config --global --unset http.sslVerify

alebo explicitne nastavte:

git config --global http.sslVerify true

Krok 2: Na Windows si vyberte medzi úložiskom certifikátov Windows a PEM zväzkom CA

Vývojári na Windows sa s touto chybou často stretávajú, keď prehliadač funguje, ale Git nie. To nutne neznamená, že je server pokazený. Prehliadač môže dôverovať firemnému koreňovému certifikátu nainštalovanému vo Windows, zatiaľ čo Git nakonfigurovaný s backendom typu OpenSSL môže používať samostatný zväzok CA.

Git podporuje hodnoty http.sslBackend ako openssl a schannel. Oficiálna dokumentácia certifikátov TLS curl vysvetľuje, že Schannel predvolene používa natívne úložisko CA Windows.

Možnosť A: Použite Schannel, keď Windows už má dôveryhodnú firemnú CA

git config --global http.sslBackend schannel

Toto je často dobrá voľba pre pracovné stanice výhradne na Windows spravované organizáciou, ktorá distribuuje dôveryhodné koreňové a medzicertifikáty prostredníctvom politiky Windows. Umožňuje Gitu spoliehať sa na rovnaký systém dôvery certifikátov Windows, ktorý môžu používať iné natívne aplikácie.

Existuje kompromis: zmena backendu mení správanie certifikátov HTTPS Gitu globálne pre daného používateľa. Ak vaša organizácia zámerne spravuje vyhradený PEM zväzok pre Git alebo automatizáciu, zostávanie pri OpenSSL môže byť predvídateľnejšie.

Aktuálna dokumentácia Gitu tiež uvádza jemné správanie Schannel: keď je Schannel vybraný prostredníctvom http.sslBackend, Git zvyčajne neaplikuje http.sslCAInfo, pretože dodaný zväzok CA by mohol prepísať úložisko certifikátov Windows. Nastavenie http.schannelUseSSLCAInfo existuje pre prostredia, ktoré toto správanie zámerne chcú.

Možnosť B: Ponechajte OpenSSL a nasmierujte Git na schválený zväzok CA

Ak vám vaša organizácia poskytne PEM zväzok obsahujúci požadované interné koreňové a medzicertifikáty, nakonfigurujte Git tak, aby používal tento súbor:

git config --global http.sslCAInfo "C:/certs/company-ca-bundle.pem"

Git definuje http.sslCAInfo ako súbor obsahujúci certifikáty používané na overenie partnera. Konfiguráciu HTTP môžete tiež obmedziť na zodpovedajúcu URL adresu namiesto zmeny každého cieľa HTTPS. Konfigurácia Gitu http.<url>.* podporuje priraďovanie špecifické pre URL podľa schémy, hostiteľa, portu a cesty.

Napríklad:

git config --global http."https://git.example.com/".sslCAInfo "C:/certs/company-ca-bundle.pem"

Toto užšie nastavenie je užitočné, keď iba interný server Git potrebuje súkromnú CA, zatiaľ čo verejné hostitelia Git by mali pokračovať v používaní normálneho zväzku dôvery.

Krok 3: Na macOS, Linux, CI a kontajneroch opravte zdroj CA, ktorý proces skutočne používa

Princíp je mimo Windows rovnaký: proces Git musí mať prístup k certifikátu CA, ktorý vydal certifikát servera alebo proxy. Presné príkazy pre úložisko dôvery systému sa líšia podľa operačného systému a distribúcie Linuxu, preto použite oficiálny mechanizmus správy certifikátov platformy alebo explicitný zväzok CA Gitu dodaný vaším správcom.

Git musí byť schopný prepojiť predložený certifikát servera cez jeho medzivydavateľov s lokálne dôveryhodnou CA.

Pre kontrolovanú úlohu CI alebo kontajner, kde nechcete meniť globálne úložisko dôvery hostiteľa, môže byť zväzok CA explicitný:

git config --global http.sslCAInfo /etc/company/git-ca-bundle.pem

alebo pre jednotlivý proces Git tiež rozpoznáva premennú prostredia GIT_SSL_CAINFO. Aktuálna dokumentácia Gitu uvádza, že táto premenná prostredia môže prepísať http.sslCAInfo.

Nekopírujte náhodný súbor cacert.pem z fóra. Ak chýbajúci certifikát je firemná CA, získajte ju od vášho IT alebo PKI tímu. Ak je vzdialený server verejná služba a váš zväzok CA je jednoducho zastaraný, aktualizujte operačný systém, distribúciu Gitu, základný obraz kontajnera alebo balík dôveryhodných CA prostredníctvom jeho normálneho kanála aktualizácií.

Firemná inšpekcia TLS je špeciálny prípad

>Niektoré podnikové proxy inšpekcie HTTPS a predkladajú náhradný certifikát podpísaný internou firemnou CA. V takejto situácii môže prehliadač uspieť, pretože firemná CA je nainštalovaná v úložisku dôvery OS, zatiaľ čo samostatný zväzok CA Gitu ju neobsahuje.

Správne riešenie je dôverovať CA organizácie prostredníctvom príslušného úložiska dôvery alebo zväzku Gitu. Neexportujte aktuálny certifikát listu a trvalo mu nedôverujte ako náhrade za vydávajúcu firemnú CA.

Rozlišujte tiež dva samostatné prípady proxy:

• Interceptácia TLS pripojenia servera Git: Firemná CA, ktorá podpisuje náhradný certifikát servera, musí byť dôveryhodná prostredníctvom normálnej cesty certifikátu servera, ako je Windows Schannel alebo http.sslCAInfo.
• HTTPS proxy, ktorého vlastné pripojenie proxy používa TLS: Git poskytuje http.proxySSLCAInfo špecificky pre zväzok CA používaný na overenie tohto pripojenia HTTPS proxy.

Git dokumentuje http.proxy a http.proxySSLCAInfo samostatne, preto použite nastavenie, ktoré zodpovedá pripojeniu, ktoré zlyháva.

Krok 4: Ak je reťazec servera neúplný, opravte server, ak môžete

Ak mnoho používateľov alebo nových strojov zlyháva na rovnakom samohostovanom serveri Git, problém môže byť na strane servera, nie zbierka pokazených klientov. Server by mal predkladať reťazec certifikátov potrebný pre klientov na prepojenie certifikátu listu s dôveryhodným vydavateľom.

Keď mnoho klientov zlyháva na jednom súkromnom hostiteľovi Git, skontrolujte reťazec servera a cestu proxy pred distribúciou obchádzok na strane klienta.

Oficiálna dokumentácia riešenia problémov so SSL GitLab špecificky opisuje unable to get local issuer certificate ako prípad, keď klient nemôže získať požadovaného vydavateľa, a odporúča buď dôverovať príslušnej CA na klientovi, alebo opraviť server tak, aby predkladal kompletný reťazec certifikátov.

Ak spravujete server, opravte nakonfigurovaný certifikát celého reťazca a znovu otestujte z čistého klienta. To je uprednostniteľné pred žiadaním každého vývojára, aby pridával ad hoc výnimky.

Overte opravu bez oslabenia TLS

Po oprave konfigurácie dôvery zopakujte rovnakú operáciu Git:

git ls-remote https://git.example.com/team/repo.git

Ak to uspeje, skúste znova pôvodnú operáciu clone, fetch, pull alebo push.

Potom skontrolujte konečnú konfiguráciu súvisiacu so zabezpečením:

git config --show-origin --get http.sslVerify
git config --show-origin --get http.sslBackend
git config --show-origin --get http.sslCAInfo

Očakávaný stav je, že verifikácia certifikátov zostáva zapnutá a Git dokáže zostaviť platný reťazec prostredníctvom zamýšľaného zdroja dôvery.

Ktorá oprava zodpovedá vašej situácii?

Situácia	Najlepší východiskový bod	Prečo
Prehliadač na Windows funguje; Git zlyháva v firemnej sieti	Skontrolujte, či je firemná CA v úložisku dôvery Windows; zvážte Schannel	Prehliadač a dôvera Windows môžu byť už správne, zatiaľ čo Git OpenSSL používa iný zväzok
Firma poskytuje PEM zväzok CA pre vývojárske nástroje	Použite http.sslCAInfo, ak je to možné, špecifické pre hostiteľa	Explicitné a reprodukovateľné pre Git, CI a kontajnery
Nový kontajner Linux zlyháva, ale pracovná stanica funguje	Nainštalujte/aktualizujte balík CA alebo pridajte CA organizácie do úložiska dôvery kontajnera/zväzku Git	Kontajner má svoj vlastný súborový systém a dôverný materiál
Iba jedna samohostovaná služba Git zlyháva pre mnohých používateľov	Skontrolujte a opravte reťazec certifikátov servera	Oprava na strane servera sa vyhne opravám pre každého klienta
HTTPS proxy má sám súkromný certifikát	Nakonfigurujte dôveryhodnú CA pre HTTPS proxy pomocou http.proxySSLCAInfo, ak je to vhodné	Verifikácia TLS proxy je oddelená od verifikácie pôvodného servera
Niekto navrhuje http.sslVerify=false	Nepoužívajte to ako trvalé riešenie	Obchádza verifikáciu certifikátu, ktorá chráni pripojenie HTTPS

Čo tak prepnúť vzdialený server Git na SSH?

SSH môže byť platnou alternatívnou prepravou, ak vaša hostingová služba Git to podporuje a vaša organizácia to povoľuje. Zmena zo vzdialeného servera HTTPS na vzdialený server SSH sa úplne vyhne reťazcu certifikátov HTTPS, ale neopraví pôvodný problém s dôverou TLS. SSH má svoj vlastný model overovania hostiteľského kľúča a správy poverení.

Používajte SSH preto, lebo zodpovedá vášmu dizajnu autentifikácie a nasadenia – nie len preto, aby ste skryli chybu konfigurácie certifikátu, ktorú budú iné nástroje HTTPS naďalej stretávať.

Bežné chyby, ktorým sa treba vyhnúť

• Vypnutie SSL verifikácie globálne. Toto odstráni verifikáciu certifikátu servera pre budúce pripojenia Git HTTPS.
• Dôvera certifikátu listu namiesto vydávajúcej CA. Certifikáty listu expirujú a rotujú; dôvera by mala byť normálne ukotvená v schválenom reťazci CA.
• Ručná úprava zväzku CA dodaného s Gitom bez zdokumentovania. Aktualizácia môže nahradiť súbor a zmena môže byť pre kolegov alebo CI nemožná na reprodukovanie.
• Predpoklad, že úspech prehliadača dokazuje, že Git má rovnaký zdroj dôvery. Git môže používať OpenSSL a samostatný PEM zväzok, zatiaľ čo prehliadač používa úložisko OS.
• Použitie http.proxySSLCAInfo pre nesprávne pripojenie. Toto nastavenie je určené na overenie HTTPS proxy, nie na všeobecnú náhradu konfigurácie CA pôvodného servera.
• Opravovanie každej vývojárskej pracovnej stanice, keď server Git posiela neúplný reťazec. Opravte server, ak ho kontrolujete.

Záver

Chyba Git SSL certificate problem: unable to get local issuer certificate je problém s reťazcom dôvery, nie problém s autentizačným tokenom a nie niečo, čo by sa normálne malo riešiť vypnutím verifikácie certifikátu. Zistite, či Git používa OpenSSL, Schannel, vlastný zväzok CA alebo HTTPS proxy; potom umiestnite schválenú vydávajúcu CA do zdroja dôvery, ktorý Git skutočne používa.

Na Windows je Schannel praktická možnosť, keď je firemná CA už spravovaná v úložisku certifikátov Windows. V CI, kontajneroch alebo prostrediach, ktoré potrebujú reprodukovateľnú dôveru založenú na súboroch, je http.sslCAInfo často prehľadnejšie. A keď mnoho klientov zlyháva na jednej samohostovanej službe, opravte reťazec certifikátov servera namiesto distribúcie nezabezpečených obchádzok.