# Pubblicazione su Gitea

Server: **http://192.168.0.183:8085**
Owner: `truetype`
Repo: `progetto2`
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/progetto2.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)

```bash
# 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": "progetto2", "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/progetto2.git`)

---

## Configurazione git locale (una tantum)

Da `/home/ubuntu/code/progetto2`:

```bash
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:

```bash
cd /home/ubuntu/code/progetto2
git init
git branch -M main
```

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

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

Push (token inline, **non** salvato):

```bash
git push https://truetype:<TOKEN>@192.168.0.183:8085/truetype/progetto2.git main
```

Verifica:

```bash
git remote -v
# deve mostrare origin → http://192.168.0.183:8085/truetype/progetto2.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:

```bash
git remote set-url origin http://192.168.0.183:8085/truetype/progetto2.git
git remote -v
# deve mostrare: origin http://192.168.0.183:8085/truetype/progetto2.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/progetto2.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:

```bash
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):

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

(in pratica è più comodo usare SSH.)

---

## Branch & tag

```bash
# 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:

```bash
cd /home/ubuntu/code/progetto2
git init
git branch -M main
git remote add origin https://192.168.0.183:8085/truetype/progetto2.git
git add .
git commit -m "Restore: progetto2 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` |