Kako odpraviti težavo s SSL certifikatom: Unable to Get Local Issuer Certificate v Gitu

Ni nobene smiselne spremembe v letu 2026, ki bi naredila staro zaobidno rešitev »izklopi SSL preverjanje« za dobro popravilo. Trenutna dokumentacija Git še vedno privzeto nastavi http.sslVerify na true in Git še vedno podpira tako zaupanje na podlagi datotek CA kot izbirne TLS ozadja, kot sta OpenSSL in Schannel. Trajna rešitev je, da Gitu zaupate pravilni certifikatni avtoriteti ali popravite nepopolno verigo strežniških certifikatov, ne pa da onemogočite preverjanje.

Napaka SSL certificate problem: unable to get local issuer certificate pomeni, da TLS knjižnica, ki jo uporablja Git, ni mogla zgraditi zaupanja vredne verige certifikatov od strežniškega certifikata do certifikatne avtoritete, ki ji zaupa. To se lahko zgodi, ker v lokalni shrambi CA manjka izdajateljska CA, korporacijski HTTPS pregledovalni proxy ponovno podpisuje promet z interno CA, Git bere napačno svežnjo CA ali samoupravljani Git strežnik ne predstavlja zahtevanih vmesnih certifikatov.

Tipična napaka Git HTTPS: oddaljeni strežnik je dosegljiv, vendar preverjanje verige certifikatov ne more najti zaupanja vrednega izdajatelja.

Začnite z najvarnejšo rešitvijo

Uporabite ta vrstni red:

1. Potrdite, katere nastavitve SSL Git in TLS ozadje so aktivne.
2. Odločite, ali manjkajoče zaupanje spada v shrambo zaupanja operacijskega sistema ali v sveženj CA Git.
3. Če veliko odjemalcev ne uspe proti istemu samogostovanemu strežniku, popravite verigo certifikatov strežnika namesto da bi krpljali vsakega odjemalca.
4. Ponovno preizkusite z vklopljenim SSL preverjanjem in odstranite morebitne začasne ali zastarele konfiguracije za obhod.

Trenutna dokumentacija git-config definira http.sslVerify, http.sslCAInfo, http.sslCAPath, http.sslBackend in obnašanje, specifično za Schannel, ki se uporablja v sistemu Windows. Privzeta vrednost za preverjanje certifikatov ostaja vklopljena.

Zanesljivo popravilo je obnovitev veljavne verige zaupanja namesto zatiranja preverjanja certifikata.

Korak 1: ugotovite, kaj Git dejansko uporablja

Pred namestitvijo certifikatov ali urejanjem konfiguracije preverite vrednosti in njihov vir:

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

Če ukaz ne izpiše ničesar, ta možnost morda preprosto uporablja privzeto vrednost Git ali libcurl. --show-origin je pomemben, ker vrednost lahko prihaja iz sistemskih, globalnih, lokalnih repozitorijev ali vključenih konfiguracijskih datotek. Popravljanje napačne ravni lahko pusti dejansko nastavitev nespremenjeno.

Preverite tudi oddaljeni strežnik, s katerim dejansko komunicirate:

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

Če Git ne uspe samo za en korporacijski ali zasebni gostitelj, medtem ko javna mesta HTTPS delujejo, je težava verjetno specifična za gostitelja ali konfiguracija strežnika. Če Git ne uspe za veliko nepovezanih oddaljenih HTTPS, najprej preverite lokalno namestitev Git, pot svežnja CA, proxy in sistemsko konfiguracijo zaupanja.

To ne naj bo vaš prvi ukaz

git config --global http.sslVerify false

To onemogoči preverjanje strežniških certifikatov za zahteve Git HTTPS na globalni ravni uporabnika. Lahko povzroči, da napaka izgine, hkrati pa odstrani zaščito, ki preverja, ali komunicirate z namenjenim strežnikom. Git dokumentira, da je preverjanje privzeto vklopljeno z razlogom.

Če odkrijete star globalni obhod, ki ni več potreben, obnovite privzeto obnašanje:

git config --global --unset http.sslVerify

ali izrecno nastavite:

git config --global http.sslVerify true

Korak 2: v sistemu Windows izberite med shrambo certifikatov Windows in svežnjem CA PEM

Razvijalci v sistemu Windows pogosto naletijo na to napako, ko brskalnik deluje, Git pa ne. To ne pomeni nujno, da je strežnik pokvarjen. Brskalnik morda zaupa korporacijskemu korenskemu certifikatu, nameščenemu v sistemu Windows, medtem ko Git, konfiguriran z ozadjem v slogu OpenSSL, morda uporablja ločen sveženj CA.

Git podpira vrednosti http.sslBackend, kot sta openssl in schannel. Uradna dokumentacija o certifikatih TLS curl pojasnjuje, da Schannel privzeto uporablja nativno shrambo CA sistema Windows.

Možnost A: uporabite Schannel, ko Windows že ima zaupanja vredno korporacijsko CA

git config --global http.sslBackend schannel

To je pogosto dobra izbira za delovne postaje samo z Windows, ki jih upravlja organizacija, ki distribuira zaupanja vredne korenske in vmesne certifikate prek politike sistema Windows. To omogoča Gitu, da se zanaša na isti sistem zaupanja certifikatom sistema Windows, ki ga lahko uporabljajo druge nativne aplikacije.

Obstaja kompromis: sprememba ozadja spremeni obnašanje certifikatov Git HTTPS globalno za tega uporabnika. Če vaša organizacija namerno upravlja z namenom določenim svežnjem PEM za Git ali avtomatizacijo, je morda bolj predvidljivo, da ostanete pri OpenSSL.

Trenutna dokumentacija Git tudi omenja subtilno obnašanje Schannel: ko je Schannel izbran prek http.sslBackend, Git običajno izogiba uporabi http.sslCAInfo, ker lahko dobavljen sveženj CA prepiše shrambo certifikatov sistema Windows. Nastavitev http.schannelUseSSLCAInfo obstaja za okolja, ki namerno želijo to obnašanje.

Možnost B: obdržite OpenSSL in usmerite Git v odobren sveženj CA

Če vam organizacija zagotovi sveženj PEM, ki vsebuje zahtevane interne korenske in vmesne certifikate, konfigurirajte Git, da uporablja to datoteko:

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

Git definira http.sslCAInfo kot datoteko, ki vsebuje certifikate, uporabljene za preverjanje sogovornika. Konfiguracijo HTTP lahko omejite tudi na ujemanje URL namesto spreminjanja vsake destinacije HTTPS. Konfiguracija Git http.<url>.* podpira ujemanje specifično za URL po shemi, gostitelju, vratih in poti.

Na primer:

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

Ta ožja nastavitev je uporabna, ko samo interni Git strežnik potrebuje zasebno CA, medtem ko bi morali javni gostitelji Git še naprej uporabljati običajni sveženj zaupanja.

Korak 3: na macOS, Linux, CI in v kontejnerjih popravite vir CA, ki ga proces dejansko uporablja

Načelo je zunaj sistema Windows enako: proces Git mora imeti dostop do certifikata CA, ki je izdal certifikat strežnika ali proxyja. Natančni ukazi za shrambo zaupanja sistema se razlikujejo glede na operacijski sistem in distribucijo Linux, zato uporabite uradni mehanizem za upravljanje certifikatov platforme ali izrecen sveženj CA Git, ki ga zagotovi vaš skrbnik.

Git mora biti sposoben povezati predstavljeni strežniški certifikat prek njegovih vmesnih izdajateljev do lokalno zaupanja vredne CA.

Za nadzorovano nalogo CI ali kontejner, kjer ne želite spremeniti globalne shrambe zaupanja gostitelja, je lahko sveženj CA izrecen:

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

ali, za posamezen proces, Git prepozna tudi spremenljivko okolja GIT_SSL_CAINFO. Trenutna dokumentacija Git navaja, da ta spremenljivka okolja lahko prepiše http.sslCAInfo.

Ne kopirajte naključne datoteke cacert.pem s foruma. Če manjkajoči certifikat je korporacijska CA, ga pridobite od vašega IT ali PKI tima. Če je oddaljeni strežnik javna storitev in je vaš sveženj CA preprosto zastarel, posodobite svoj operacijski sistem, distribucijo Git, osnovno sliko kontejnerja ali paket zaupanja vrednih CA prek običajnega kanala posodobitev.

Korporacijski TLS pregled je poseben primer

Nekateri korporacijski proxyji pregledujejo HTTPS in predstavijo nadomestni certifikat, podpisan z interno korporacijsko CA. V tej situaciji lahko brskalnik uspe, ker je korporacijska CA nameščena v shrambi zaupanja OS, medtem ko ločen sveženj CA Git ne vsebuje.

Pravilna rešitev je, da zaupate CA organizacije prek ustrezne shrambe zaupanja ali svežnja Git. Ne izvažajte trenutnega listnega certifikata in trajno zaupajte temu kot nadomestku za izdajateljsko korporacijsko CA.

Razlikujte tudi dva ločena primera proxyja:

• Prisluškovanje TLS povezavi Git strežnika: korporacijska CA, ki podpisuje nadomestni strežniški certifikat, mora biti zaupanja vredna prek običajne poti strežniškega certifikata, kot je Schannel v sistemu Windows ali http.sslCAInfo.
• HTTPS proxy, katerega lastna proxy povezava uporablja TLS: Git zagotavlja http.proxySSLCAInfo izrecno za sveženj CA, uporabljen za preverjanje te povezave HTTPS proxy.

Git dokumentira http.proxy in http.proxySSLCAInfo ločeno, zato uporabite nastavitev, ki ustreza povezavi, ki ne uspe.

Korak 4: če je veriga strežnika nepopolna, popravite strežnik, ko lahko

Če veliko uporabnikov ali novih naprav ne uspe proti istemu samogostovanemu Git strežniku, je lahko težava na strani strežnika in ne zbirka pokvarjenih odjemalcev. Strežnik bi moral predstaviti verigo certifikatov, ki jo odjemalci potrebujejo za povezavo listnega certifikata do zaupanja vrednega izdajatelja.

Ko veliko odjemalcev ne uspe proti enemu zasebnemu gostitelju Git, preverite verigo strežnika in pot proxyja pred distribucijo obhodov na strani odjemalca.

Uradna dokumentacija za odpravljanje težav SSL GitLab specifično opisuje unable to get local issuer certificate kot primer, kjer odjemalec ne more pridobiti zahtevanega izdajatelja, in priporoča bodisi zaupanje ustrezni CA na odjemalcu bodisi popravilo strežnika, da predstavi popolno verigo certifikatov.

Če upravljate strežnik, popravite konfiguriran certifikat polne verige in ponovno preizkusite s čistega odjemalca. To je boljše kot zahtevati od vsakega razvijalca, da doda ad hoc izjeme.

Preverite popravilo brez oslabitve TLS

Po tem, ko je konfiguracija zaupanja popravljena, ponovite isto operacijo Git:

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

Če to uspe, poskusite znova z originalnim clone, fetch, pull ali push.

Nato preverite končno varnostno povezano konfiguracijo:

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

Pričakano stanje je, da preverjanje certifikatov ostane vklopljeno in Git lahko zgradi veljavno verigo prek namenjenega vira zaupanja.

Katera rešitev ustreza vaši situaciji?

Kaj pa preklop oddaljenega Git na SSH?

SSH je lahko veljavna alternativna transportna plast, če vaša storitev gostovanja Git to podpira in vaša organizacija to dovoljuje. Sprememba iz oddaljenega HTTPS na oddaljeni SSH se izogne celotni verigi certifikatov HTTPS, vendar ne popravi prvotne težave s zaupanjem TLS. SSH ima svoj lasten model preverjanja gostiteljskih ključev in upravljanja poverilnic.

Uporabite SSH, ker ustreza vaši zasnovi za preverjanje pristnosti in uvajanje, ne zgolj zato, da skrijete napako pri konfiguraciji certifikatov, ki jo bodo druga orodja HTTPS še naprej naletela.

Pogoste napake, ki se jim je treba izogniti

• Globalno onemogočanje preverjanja SSL. To odstrani preverjanje strežniških certifikatov za prihodnje povezave Git HTTPS.
• Zaupanje listnemu certifikatu namesto izdajateljski CA. Listni certifikati potečejo in se menjavajo; zaupanje bi moralo biti običajno sidrano v odobreni verigi CA.
• Ročno urejanje vgrajene datoteke CA Git brez dokumentiranja. Nadgradnja lahko zamenja datoteko, sprememba pa je morda nemogoče ponoviti za sodelavce ali CI.
• Privzemanje, da uspeh brskalnika dokazuje, da ima Git isti vir zaupanja. Git morda uporablja OpenSSL in ločen sveženj PEM, medtem ko brskalnik uporablja shrambo OS.
• Uporaba http.proxySSLCAInfo za napačno povezavo. Ta nastavitev je za preverjanje HTTPS proxyja, ne splošna zamenjava za konfiguracijo CA izvornega strežnika.
• Krpljenje vsake delovne postaje razvijalca, ko Git strežnik pošilja nepopolno verigo. Popravite strežnik, ko ga nadzorujete.

Zaključek

Napaka Git SSL certificate problem: unable to get local issuer certificate je težava verige zaupanja, ne težava žetona za preverjanje pristnosti in ne nekaj, kar bi bilo običajno treba rešiti z izklopom preverjanja certifikatov. Ugotovite, ali Git uporablja OpenSSL, Schannel, sveženj CA po meri ali HTTPS proxy; nato postavite odobreno izdajateljsko CA v vir zaupanja, ki ga Git dejansko uporablja.

V sistemu Windows je Schannel praktična možnost, ko je korporacijska CA že upravljana v shrambi certifikatov sistema Windows. V CI, kontejnerjih ali okoljih, ki potrebujejo ponovljivo zaupanje na podlagi datotek, je http.sslCAInfo pogosto jasnejši. In ko več odjemalcev ne uspe proti eni samogostovani storitvi, popravite verigo certifikatov strežnika namesto da bi distribuirali nezavarne obhode.