viandante/docs/gitea.md

Pubblicazione su Gitea

Server: http://192.168.0.183:8085 Owner: truetype Repo: viandante Branch iniziale: main

---

⚠️ Sicurezza del token

Il token Gitea in colonna truetype (stringa 40‑hex) fornisce accesso completo all'account e ai suoi repo. Regole non negoziabili:

1. Non committare mai il token nel repo. Il comando di push sotto lo passa inline nell'URL di una sola git push. Mai git config credential.helper, mai .netrc committato, mai variabili d'ambiente in uno script versionato.
2. Revoca dopo l'uso. Dopo il primo push riuscito, vai su http://192.168.0.183:8085/user/settings/applications → revoca il token usato. Generane uno nuovo solo se ti serve un altro push. Conserva il vecchio token solo se prevedi push automatici da CI (allora mettilo nei secrets della pipeline, non nel codice).
3. Preferisci token scoped: quando ne crei uno nuovo, limita repository.write e basta, non repository.admin.
4. HTTPS vs SSH. Se hai una chiave SSH sull'account Gitea, preferisci sempre SSH: git@192.168.0.183:8085:truetype/viandante.git (nota: Gitea usa :owner/repo.git dopo il :). Nessun token in chiaro è necessario.

I log di esempio in questo file usano il placeholder <TOKEN>. Non sostituirlo durante la lettura: il token reale dovrebbe vivere solo nella shell history dell'operatore.

---

Creazione del repo (una tantum)

# 1: crea il repo via API (body JSON minimo)
curl -X POST http://192.168.0.183:8085/api/v1/user/repos \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "viandante", "description": "MUD client (Dead Souls / LP-MUD)", "auto_init": false, "private": false}'

Risposta attesa: 201 Created con JSON contenente id, ssh_url, clone_url, html_url. Annota:

• html_url (visibile in browser)
• clone_url (es. http://192.168.0.183:8085/truetype/viandante.git)

---

Configurazione git locale (una tantum)

Da /home/ubuntu/code/viandante:

git config user.name  "truetype"
git config user.email "truetype@192.168.0.183"

(Non mettere user.email reale se non vuoi che appaia nei commit.)

---

Primo push

Se .git/ non esiste ancora:

cd /home/ubuntu/code/viandante
git init
git branch -M main

Commit iniziale (esclude venv, pycache, cache pytest via .gitignore già presente):

git add .
git commit -m "Initial commit: MUD client v0.2 (cli, telnet, gmcp, mapper, deadsouls, logger, tests)"

Push (token inline, non salvato):

git push https://truetype:<TOKEN>@192.168.0.183:8085/truetype/viandante.git main

Verifica:

git remote -v
# deve mostrare origin → http://192.168.0.183:8085/truetype/viandante.git

git log --oneline -5

Dopo il push, revoca <TOKEN> come da sezione sicurezza.

Strip delle credenziali dalla config locale

Dopo un push con URL https://user:token@host/..., Gitea lascia l'URL completo (con token!) scritto in .git/config. Rimuovi subito le credenziali:

git remote set-url origin http://192.168.0.183:8085/truetype/viandante.git
git remote -v
# deve mostrare: origin http://192.168.0.183:8085/truetype/viandante.git (no user:token@)

Da questo momento i push successivi richiederanno il token solo se usi HTTPS nudo. Per evitare di digitarlo ogni volta, configura una chiave SSH (http://192.168.0.183:8085/user/settings/keys) e cambia il remote in git@192.168.0.183:8085:truetype/viandante.git.

---

Push successivi (senza token)

Dopo aver configurato git remote add origin ... con un URL senza credenziali (es. SSH o HTTPS nudo), i push successivi sono:

git add .
git commit -m "Fix: ..."
git push origin main

Se devi restare su HTTPS, configura un credential helper temporaneo nella shell (niente su disco):

GIT_ASKPASS=/bin/true git -c credential.helper= -c core.askPass=/bin/true push origin main

(in pratica è più comodo usare SSH.)

---

Branch & tag

# feature branch
git checkout -b feature/msdp-support
git push -u origin feature/msdp-support

# tag di release
git tag -a v0.2.0 -m "release v0.2.0"
git push origin v0.2.0

I tag abilitano la releases page di Gitea; usa i tag vX.Y.Z come nomi dei binari / delle release notes.

---

Re‑push dopo perdita di .git/

Se per qualunque motivo il .git/ locale viene perso:

cd /home/ubuntu/code/viandante
git init
git branch -M main
git remote add origin https://192.168.0.183:8085/truetype/viandante.git
git add .
git commit -m "Restore: viandante v0.2"
git push -u origin main
# NB: questo push richiede di nuovo un token se SSH non è configurato

---

Webhook di release (opzionale)

Per triggerare un deploy o un CI su tag push:

1. In Gitea: Repo → Settings → Webhooks → Add webhook
2. URL: il tuo endpoint CI (es. Drone, Woodpecker, Gitea Actions)
3. Events: Push events + Create events (quest'ultimo copre i tag)
4. Secret: <WEBHOOK_SECRET> (salvalo nei secrets della CI, non nel codebase).

---

Troubleshooting

Errore	Causa	Rimedio
403 Forbidden	token errato o revocato	rigenera; controlla che lo scope includa repo
401 Unauthorized	token mancante o scaduto	verifica header Authorization
repository does not exist	repo non creato lato Gitea	ricrea via API; assicurati che owner/name siano giusti
failed to push some refs	remote ahead	git pull --rebase origin main poi push
Could not resolve host	Gitea offline	controlla curl http://192.168.0.183:8085/api/v1/version
Permission denied (publickey)	SSH non configurato	aggiungi la chiave pubblica a http://192.168.0.183:8085/user/settings/keys