Risoluzione degli errori comuni di autenticazione Git utilizzando SSH e token
Risolvi i comuni errori di autenticazione Git abbinando l'URL remoto alle chiavi SSH, ai token HTTPS e agli helper delle credenziali.
Risoluzione degli errori comuni di autenticazione Git utilizzando SSH e token
La maggior parte dei problemi di autenticazione Git deriva da una discrepanza tra l'URL remoto, le credenziali che Git sta cercando di utilizzare e le autorizzazioni sull'account di hosting Git. Il testo dell'errore può sembrare drammatico, ma la soluzione è solitamente meccanica una volta che si conosce il percorso che Git sta seguendo.
Inizia con l'URL remoto:
git remote -v
Se vedi https://github.com/org/repo.git, Git sta utilizzando HTTPS e avrà bisogno di un nome utente più un token o un helper di credenziali in grado di fornirne uno. Se vedi [email protected]:org/repo.git, Git sta utilizzando SSH e avrà bisogno di una chiave privata che corrisponda a una chiave pubblica registrata con l'host.
Non mescolare i due durante la risoluzione dei problemi. Scegli HTTPS o SSH, fai corrispondere l'URL remoto, quindi testa direttamente quel percorso.
Leggi l'errore letteralmente
fatal: Authentication failed for 'https://...' di solito significa che Git ha raggiunto il server ma non ha presentato una credenziale HTTPS valida. La vecchia credenziale potrebbe essere memorizzata nella cache, il token potrebbe essere scaduto o il token potrebbe non avere accesso a quel repository.
remote: Permission to org/repo denied o 403 Forbidden di solito significa che la tua identità è stata riconosciuta ma non ha l'autorizzazione per l'operazione. Ad esempio, potresti utilizzare un token dell'account sbagliato, un token senza accesso in scrittura o una chiave SSH collegata a un utente diverso.
Permission denied (publickey) significa che SSH non ha offerto una chiave che il server accetta.
Un prompt ripetuto di nome utente/password su HTTPS di solito significa che Git continua a ricevere un rifiuto e a chiedere di nuovo. Digitare ripetutamente la password dell'account non aiuterà sugli host che richiedono token per le operazioni Git.
Correggere HTTPS con un token di accesso personale
Per i remoti HTTPS, crea un token di accesso personale nelle impostazioni dell'account del tuo host Git. I nomi esatti dei menu differiscono tra GitHub, GitLab, Bitbucket e piattaforme self-hosted, ma la forma è la stessa: crea un token, concedigli l'accesso al repository, imposta una scadenza che corrisponda alla politica della tua organizzazione e copialo immediatamente.
Quando Git ti richiede, usa il tuo nome utente normale e incolla il token come password:
Username: your-username
Password: <paste-token-here>
Utilizza le autorizzazioni più ristrette che funzionano. Per un repository privato su cui esegui il push, hai bisogno di accesso in lettura e scrittura al repository. Per clonare repository pubblici, potresti non aver bisogno di alcun token. I token granulari e le regole SSO dell'organizzazione possono aggiungere un altro livello: un token può esistere ma necessitare ancora di approvazione o autorizzazione SSO prima di poter accedere a un repository aziendale.
Se Git non richiede mai il nuovo token, probabilmente sta utilizzando una vecchia credenziale memorizzata nella cache. Cancella la voce memorizzata per l'host, quindi riprova.
Su macOS, controlla l'Accesso Portachiavi per le voci relative al tuo host Git, come github.com o git:https://github.com.
Su Windows, apri Gestione credenziali e rimuovi la credenziale generica pertinente per l'host.
Su Linux, ispeziona il tuo helper configurato:
git config --global --get credential.helper
git config --show-origin --get-all credential.helper
L'helper cache memorizza temporaneamente le credenziali in memoria. L'helper store le scrive su disco in testo semplice a meno che non si configuri un livello di archiviazione più sicuro, quindi usalo con cautela. Il sistema di helper delle credenziali di Git è progettato per chiedere agli helper le credenziali e consentire agli helper di salvare quelle riuscite; la sicurezza dipende dall'helper che scegli.
Una sequenza utile di ripristino HTTPS è:
git remote -v
git config --show-origin --get-all credential.helper
# rimuovi la vecchia credenziale dall'archivio credenziali del sistema operativo
git ls-remote origin
git ls-remote origin è un test pulito perché contatta il remoto senza modificare il tuo albero di lavoro.
Correggere SSH con le chiavi
Per i remoti SSH, controlla prima se hai già delle chiavi:
ls -al ~/.ssh
I nomi comuni delle chiavi includono id_ed25519, id_rsa e nomi specifici dell'host come github_work_ed25519. Il file .pub è la chiave pubblica che carichi sull'host Git. Il file senza .pub è privato e non deve essere condiviso.
Se hai bisogno di una nuova chiave, Ed25519 è una buona opzione predefinita sui sistemi moderni:
ssh-keygen -t ed25519 -C "[email protected]"
Usa una passphrase a meno che il tuo ambiente non abbia un motivo specifico di automazione per non farlo. Quindi aggiungi la chiave pubblica al tuo account host Git o alle impostazioni delle chiavi di deploy:
cat ~/.ssh/id_ed25519.pub
Testa la connessione direttamente:
ssh -T [email protected]
Per GitLab o Bitbucket, sostituisci il nome dell'host. Un test riuscito di solito stampa un saluto o un messaggio che dice che l'accesso alla shell non è fornito. Va bene; l'autenticazione Git-over-SSH può comunque funzionare.
Se SSH fallisce ancora, chiedi al client SSH cosa sta facendo:
ssh -vT [email protected]
Cerca le righe che mostrano quali chiavi vengono offerte. Se la tua chiave non viene offerta, caricala nell'agente:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
Per più account sullo stesso host, usa ~/.ssh/config in modo che Git sappia quale chiave appartiene a quale remoto:
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/github_work_ed25519
IdentitiesOnly yes
Quindi punta il repository a quell'alias:
git remote set-url origin git@github-work:org/repo.git
Questo evita il problema comune in cui SSH offre la tua chiave personale a un repository di lavoro.
Cambiare protocollo in modo pulito
Se il tuo team standardizza su SSH, cambia un remoto HTTPS in questo modo:
git remote set-url origin [email protected]:ORG/REPO.git
Se la tua azienda blocca SSH o richiede l'ispezione HTTPS, cambia nell'altro senso:
git remote set-url origin https://github.com/ORG/REPO.git
Dopo aver cambiato l'URL, testa con un'operazione di lettura:
git fetch origin
Quindi testa l'azione che ha fallito:
git push origin HEAD
Se il fetch funziona ma il push fallisce, probabilmente l'autenticazione è valida e il problema è l'autorizzazione. Controlla la protezione dei branch, il ruolo del repository, l'ambito del token e le regole SSO dell'organizzazione.
Ambienti CI e server
Su agenti di build e server, evita di utilizzare il token personale di un umano quando possibile. Preferisci chiavi di deploy, utenti macchina o l'archivio credenziali integrato del tuo sistema CI. Mantieni i segreti fuori dalla cronologia dei comandi e dai log. Non incollare token negli URL remoti in questo modo a meno che tu non sia in un ambiente usa e getta controllato:
https://[email protected]/org/repo.git
Quello stile può trapelare attraverso log, elenchi di processi, cronologia della shell e file di configurazione.
Per Jenkins, runner di GitHub Actions, runner di GitLab e sistemi simili, archivia le credenziali nel meccanismo segreto della piattaforma e iniettarle solo per il lavoro che ne ha bisogno.
Una rapida lista di controllo
Esegui questi in ordine quando sei bloccato:
git remote -v
git ls-remote origin
Se l'URL è HTTPS, cancella le vecchie credenziali memorizzate nella cache e usa un token corrente con le autorizzazioni corrette per il repository.
Se l'URL è SSH, esegui:
ssh -T git@your-hostname
ssh -vT git@your-hostname
Conferma che la chiave prevista viene offerta e che la sua metà pubblica è registrata con l'account corretto.
Se l'autenticazione riesce ma il push fallisce, cerca le regole di autorizzazione: branch protetti, ruolo di scrittura mancante, autorizzazione SSO scaduta, chiavi di deploy di sola lettura o token senza autorizzazione di scrittura.
La soluzione affidabile non è provare password casuali. Abbina il protocollo remoto al tipo di credenziale, rimuovi le credenziali obsolete memorizzate nella cache, testa la connessione direttamente e poi controlla le autorizzazioni sul repository.