Token GitHub e autenticazione Git: personal access token, Git Credential Manager, push senza password

Perché Git non accetta più la password di GitHub

Se con git push inserite login e password di github.com e ricevete un rifiuto, il problema non è un errore di battitura. Dal 13 agosto 2021 GitHub ha disattivato l'accesso con password per le operazioni Git via HTTPS. Al posto della password servono un token GitHub (personal access token, PAT) oppure l'autenticazione nel browser gestita da Git Credential Manager.

Il messaggio di errore appare così:

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/... for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/user/project.git/'

Il motivo è semplice: la password dell'account dà accesso completo a tutto, non si può limitare a un solo repository ed è scomoda da revocare. Un token invece si crea per un'attività specifica, ha una scadenza e un insieme di permessi, e in caso di fuga si elimina in un minuto senza cambiare la password. GitLab e Bitbucket hanno seguito la stessa strada, quindi quanto descritto qui vale in sostanza anche per loro.

Due modi di autenticarsi: HTTPS e SSH

Git comunica con il repository remoto con uno di due protocolli, e da questo dipende il modo di accesso.

Le chiavi SSH si configurano una volta sola, e poi Git non chiede più né login né password. La loro creazione e l'aggiunta su GitHub sono spiegate nell'articolo sulla configurazione di Git; qui ci concentriamo su HTTPS, perché è lì che i principianti vedono più spesso la richiesta della password. Per sapere quale protocollo usa il vostro repository, eseguite:

git remote -v
origin  https://github.com/user/project.git (fetch)
origin  https://github.com/user/project.git (push)

Come creare un token GitHub (personal access token)

Il personal access token è una lunga stringa casuale che GitHub rilascia al posto della password per l'accesso programmatico. I token classic iniziano con ghp_, quelli fine-grained con github_pat_. Il token viene mostrato una sola volta, subito dopo la creazione, quindi copiatelo in un gestore di password.

Passo per passo

1. Accedete a github.com, cliccate sull'avatar in alto a destra e aprite Settings.
2. In fondo al menu a sinistra scegliete Developer settings, poi Personal access tokens.
3. Scegliete il tipo: Fine-grained tokens (consigliato) oppure Tokens (classic), e premete il pulsante per generare un nuovo token.
4. Assegnate un nome chiaro (per esempio «portatile, lavoro»), una scadenza e i permessi.
5. Premete il pulsante di generazione e copiate subito il token.

Fine-grained o classic

Il token fine-grained si limita a repository specifici e a singoli permessi. Per il lavoro normale sul codice scegliete i repository necessari e, nei permessi sui repository, date Contents: Read and write: basta per clone, pull e push. Se leggete soltanto un repository privato, è sufficiente Read-only.

Il token classic vale per tutti i vostri repository insieme. Per il push serve l'ambito repo, per modificare i file in .github/workflows serve anche workflow. Il classic è più semplice ma più pericoloso: una fuga dà accesso a tutto l'account.

Scadenza

GitHub propone diverse durate e permette di indicare una data precisa. Un token senza scadenza si può creare, ma non conviene: un token eterno dimenticato è un classico buco di sicurezza. Ha senso impostare 30–90 giorni e rigenerarlo quando GitHub invia il promemoria via e-mail prima della scadenza.

Git push e git clone con il token

Usare il token è più semplice di quanto sembri: Git chiede «Password», e ci inserite il token al posto della password.

$ git push origin main
Username for 'https://github.com': your-login
Password for 'https://your-login@github.com': <incollate il token>

Nel terminale i caratteri della password non vengono visualizzati: è normale, incollate il token e premete Invio. In Git Bash su Windows l'incolla funziona con Shift+Insert o con il tasto destro del mouse.

Git clone con token

Un repository privato si clona nello stesso modo: git clone chiede login e token. Se volete evitare le domande, per esempio in uno script, potete inserire il token direttamente nell'indirizzo:

git clone https://your-login:<TOKEN>@github.com/user/project.git

Attenzione allo svantaggio: l'indirizzo con il token viene salvato in .git/config e può finire nella cronologia della shell. Dopo il clone conviene rimuovere il token dall'indirizzo:

git remote set-url origin https://github.com/user/project.git

Nei sistemi CI il token si passa tramite variabili d'ambiente segrete, non si scrive nei file. In GitHub Actions per il repository corrente esiste già il GITHUB_TOKEN integrato, quindi spesso non serve un PAT separato.

GitLab: git clone con token

In GitLab il token si crea nelle impostazioni del profilo, nella sezione Access tokens; per lavorare con il codice servono gli ambiti read_repository e write_repository. Lo schema è lo stesso: il login GitLab come nome utente, il token come password.

git clone https://oauth2:<TOKEN>@gitlab.com/group/project.git

GitLab accetta il nome oauth2 per qualsiasi token personale; al suo posto potete indicare il vostro login.

Git pull e fetch

Per un repository pubblico, git pull e git clone funzionano senza autenticazione. Login e token vengono richiesti solo per i repository privati o per git push. Se un pull su un progetto pubblico chiede una password, di solito l'indirizzo contiene un errore: GitHub risponde a un repository inesistente come a uno chiuso.

Git Credential Manager: cos'è

Inserire il token a ogni push è scomodo. Questo compito spetta al credential helper, un programma di supporto che Git richiama quando servono le credenziali. Git gli passa l'indirizzo del server, ed esso restituisce login e password (o token) dal proprio archivio.

Git Credential Manager (GCM) è il helper più comodo. È un programma multipiattaforma di GitHub e Microsoft: al primo push apre una finestra di accesso o il browser, vi autenticate su GitHub (anche con l'autenticazione a due fattori), e GCM ottiene il token da solo e lo conserva nell'archivio protetto del sistema. In questo caso non serve creare a mano un PAT.

GCM supporta GitHub, GitLab, Bitbucket e Azure DevOps. In Git per Windows è installato per impostazione predefinita: è la scelta del credential helper nel programma di installazione.

Quali credential.helper esistono

Configurare l'autenticazione Git su Windows, macOS e Linux

Per vedere quale helper è già impostato:

git config --show-origin --get-all credential.helper

Windows

Se durante l'installazione di Git avete lasciato le impostazioni predefinite, GCM funziona già: al primo push da Git Bash, PowerShell o VS Code si apre la finestra di accesso a GitHub. Se l'helper non è configurato, attivatelo a mano:

git config --global credential.helper manager

macOS

Su Mac Git di solito usa già osxkeychain: il token inserito una volta finisce nel Portachiavi. Per ottenere l'accesso nel browser installate Git Credential Manager (per esempio con Homebrew: brew install --cask git-credential-manager), che si configura da solo.

Linux

Su Linux GCM si installa a parte (pacchetto .deb o archivio dalle release del progetto), poi si esegue la configurazione e si sceglie l'archivio:

git-credential-manager configure
git config --global credential.credentialStore secretservice

Su un server senza interfaccia grafica è più semplice una cache temporanea:

git config --global credential.helper 'cache --timeout=3600'

Alternativa per GitHub: gh auth login

Se avete installato GitHub CLI, il comando gh auth login guida l'accesso nel browser, e gh auth setup-git configura Git in modo che prenda le credenziali da gh. È un modo comodo per «fare login in Git Bash» con un solo comando.

Come cancellare o aggiornare la password Git salvata

La situazione più frequente: il token è scaduto oppure avete cambiato account, e Git continua a usare i vecchi dati e ottiene Authentication failed. Bisogna eliminare la voce salvata: al push successivo Git chiederà di nuovo le credenziali.

Comando universale

Funziona con qualsiasi helper:

printf "protocol=https\nhost=github.com\n\n" | git credential reject

Git reset credentials su Windows

Aprite «Pannello di controllo» → «Gestione credenziali» → «Credenziali di Windows», cercate le voci del tipo git:https://github.com ed eliminatele. Lo stesso si può fare dal prompt dei comandi:

cmdkey /list | findstr git
cmdkey /delete:git:https://github.com

Se usate GCM, esiste un suo comando per uscire dall'account: git credential-manager github logout <login>.

macOS

Aprite «Accesso Portachiavi», cercate la voce github.com di tipo «Password Internet» ed eliminatela. Oppure dal terminale:

git credential-osxkeychain erase
host=github.com
protocol=https

Dopo l'ultima riga premete di nuovo Invio, per inviare la riga vuota.

Linux e store

Per store eliminate la riga con github.com da ~/.git-credentials; per cache eseguite git credential-cache exit.

Errori di autenticazione e come risolverli

Support for password authentication was removed

Avete inserito la password dell'account. Create un token e incollatelo nel campo Password, oppure configurate Git Credential Manager. Se l'errore si ripete senza che venga chiesta la password, significa che nell'archivio è salvata la vecchia password: eliminatela come descritto sopra.

git push: Authentication failed

Cause in ordine di frequenza: il token è scaduto; il token è stato revocato; il token fine-grained non ha accesso a questo repository oppure il permesso Contents è solo in lettura; nell'archivio sono rimasti i dati di un altro account. Verificate scadenza e permessi del token in Developer settings e cancellate le credenziali salvate.

remote: Permission denied (403)

L'autenticazione è riuscita, ma il vostro account non ha il diritto di scrittura su questo repository. Il proprietario deve aggiungervi tra i Collaborators, oppure lavorate tramite il vostro fork e una pull request.

Repository not found

Per un repository privato GitHub non rivela se esiste, quindi con un token errato risponde «not found». Controllate l'indirizzo con git remote -v e i permessi del token.

Git clone chiede la password ogni volta

Il credential helper non è configurato. Attivate manager oppure osxkeychain: dopo il primo inserimento riuscito Git smette di chiedere. In alternativa passate a SSH.

Come conservare il token in sicurezza

• Concedete il minimo dei permessi: un token fine-grained sui repository necessari al posto di un classic con repo.
• Impostate una scadenza e rigenerate il token, invece di prolungarlo all'infinito.
• Non committate i token e non inseriteli negli indirizzi remote; se un token finisce in un repository pubblico, GitHub potrebbe revocarlo automaticamente, ma consideratelo compromesso e eliminatelo voi.
• Usate l'archivio di sistema (GCM, Portachiavi) invece di store.
• Un token per ogni macchina o attività: in caso di fuga revocate solo quello.

Conclusioni

La password di GitHub non funziona per Git via HTTPS dal 2021. Ci sono tre strade valide: accedere con Git Credential Manager nel browser, creare un token GitHub da inserire al posto della password, oppure passare alle chiavi SSH. Il token si crea in Settings → Developer settings, lo memorizza il credential.helper, e in caso di errore Authentication failed di solito basta rigenerare il token e cancellare le vecchie credenziali. Connessione a GitHub e lavoro con i repository remoti sono trattati nella pratica nel corso su Git.