Git

Credenziali Forgejo via HTTPS con `pass` su Arch Linux

Credenziali Forgejo via HTTPS con `pass` su Arch Linux

Guida per autenticarsi a Forgejo via HTTPS (senza SSH) memorizzando le credenziali in modo cifrato con pass, con integrazione automatica in git tramite pass-git-helper.

Esempio basato sull'host forgejo.dominio.tdl. Sostituisci dominio e nome utente con i tuoi.

Prerequisiti

Arch Linux
Una chiave GPG (la creiamo se manca)
Pacchetti: pass, un editor (nano o vim), pass-git-helper (AUR)

1. Genera un token in Forgejo

Non usare la password dell'account. In Forgejo:

Impostazioni → Applicazioni → Genera nuovo token

Assegna almeno lo scope di lettura e scrittura sui repository (read/write:repository) — serve per il push — e copia subito il token (viene mostrato una sola volta).

Vantaggi del token: è revocabile, ha permessi limitati e funziona anche con la 2FA attiva.

2. Prepara GPG e pass

pass cifra le credenziali con GPG, quindi serve una chiave.

# Crea una chiave GPG solo se non ne hai già una
gpg --full-generate-key

# Installa pass e inizializzalo con la tua chiave
sudo pacman -S pass
pass init <ID-o-email-della-tua-chiave-GPG>

Per trovare l'ID di una chiave esistente: gpg --list-secret-keys --keyid-format long

3. Salva il token in pass

pass insert git/forgejo.dominio.tdl

Inserisci il token come password. Confermalo quando richiesto.

Per verificare il contenuto salvato:

pass git/forgejo.dominio.tdl

La prima riga deve contenere solo il token.

4. Installa pass-git-helper

È disponibile nell'AUR:

yay -S pass-git-helper
# in alternativa: pipx install pass-git-helper

5. Configura la mappatura host → voce di pass

Crea il file ~/.config/pass-git-helper/git-pass-mapping.ini:

[forgejo.dominio.tdl]
target=git/forgejo.dominio.tdl
username=il-tuo-utente

username deve essere il tuo nome utente di login Forgejo. Specificarlo qui evita ambiguità: l'autenticazione avviene con username + token come password.

6. Configura git per usare l'helper

git config --global credential.helper "$(which pass-git-helper)"

Verifica che non ci siano altri helper che interferiscono (es. store, cache, libsecret), perché git userebbe il primo che risponde:

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

Se ne trovi più di uno, lascia solo pass-git-helper:

git config --global --unset-all credential.helper
git config --global credential.helper "$(which pass-git-helper)"

7. Uso quotidiano

Clona e usa i repository via HTTPS normalmente:

git clone https://forgejo.dominio.tdl/utente/repo.git
cd repo
git pull
git push

Alla prima operazione GPG ti chiederà la passphrase (poi gestita da gpg-agent). Nessuna password o token in chiaro sul disco.

Risoluzione problemi

`vi: comando non trovato` durante `pass edit`

pass usa l'editor in $EDITOR e, se non impostato, ripiega su vi.

Soluzione temporanea:

EDITOR=nano pass edit git/forgejo.dominio.tdl

Soluzione permanente — aggiungi in ~/.bashrc (o ~/.zshrc):

export EDITOR=nano

Poi source ~/.bashrc.

`Autenticazione non riuscita` / credenziali rifiutate al push

Verifica cosa restituisce davvero l'helper:

printf 'protocol=https\nhost=forgejo.dominio.tdl\n\n' | pass-git-helper get

Deve stampare due righe:

password=<il-tuo-token>
username=<il-tuo-utente>

Controlli da fare:

Manca username= → aggiungi username= nel file .ini (punto 5).
password= vuoto o errato → la voce pass è sbagliata, risalvala (pass insert --multiline git/forgejo.dominio.tdl, token sulla prima riga, poi Ctrl+D).
Helper multipli → vedi punto 6, lascia solo pass-git-helper.
Token scaduto o senza permessi di scrittura → rigeneralo in Forgejo con lo scope corretto e risalvalo.
Credenziali vecchie in cache:

git credential-cache exit 2>/dev/null
rm -f ~/.git-credentials 2>/dev/null

Test rapido della credenziale senza fare push:

git ls-remote https://forgejo.dominio.tdl/utente/repo.git

Git