From 0cd2dafb098ac261c559f264dbd4b555751a384a Mon Sep 17 00:00:00 2001
From: alvis <allogn@gmail.com>
Date: Sun, 14 Jun 2026 10:22:24 +0000
Subject: [PATCH] Gitea: add SSH troubleshooting (regenerate keys, port 222)

---
 Gitea.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Gitea.md b/Gitea.md
index ac6612b..d0b5f86 100644
--- a/Gitea.md
+++ b/Gitea.md
@@ -72,6 +72,31 @@ Config: `/etc/zabbix/zabbix_agent2.d/gitea_backup.conf`
 
 > **Note:** Items and triggers are already configured via the Zabbix API.
 
+## Troubleshooting
+
+### SSH push fails with `Permission denied (publickey)`
+
+After a container rebuild/recreate, Gitea's `authorized_keys` can lose the user keys (only the internal `Gitea Host Key` remains in `/data/git/.ssh/authorized_keys`), even though the keys are still registered in the database. Symptom: `git push` over SSH is rejected although the key shows up under *Settings → SSH Keys*.
+
+Rebuild `authorized_keys` from the database:
+
+```bash
+docker exec -u git gitea gitea admin regenerate keys
+```
+
+Verify the user key is back:
+
+```bash
+docker exec gitea grep ssh-ed25519 /data/git/.ssh/authorized_keys
+```
+
+> **Run this after any `gitea` container rebuild** if SSH access stops working.
+
+### SSH port / remote URL
+
+- Gitea SSH listens on host port **222** (mapped to container `22`).
+- `git.alogins.net:222` is **not** reachable externally (not forwarded). Pushing from the Agap host itself must use `ssh://git@localhost:222/<user>/<repo>.git`.
+
 ## Stack
 
 - Gitea 1.25.3