local_machine/docs/apps/git/RUNBOOK.md

Runbook: Git / Gitea — push local_machine

Симптом: не удаётся запушить в Gitea, git push зависает, auth error, «repository not found», или нужен первый push.

Репозиторий: local_machine → https://gitea.hunab.app/hunabgit/local_machine
Корень на Mac: /Users/eternal/code/local_machine

---

Архитектура (кратко)

Mac (local_machine)  ──git push──►  Gitea (209.38.32.21 / gitea.hunab.app)
                                      PostgreSQL, контейнер gitea, SSH :2223

Из РФ прямой HTTPS/SSH часто нестабилен → цепочка Mac → RU (hsites-ahau) → DO (209.38.32.21) или bundle на зеркало 206.189.35.205.

Компонент	Значение
Remote origin	SSH :2223 или HTTPS (см. git remote -v)
Ветка	main
SSH ключ Gitea	~/.ssh/hunab_deploy_key
SSH hop RU	hsites-ahau, ~/.ssh/id_ed25519
Скрипт push через прокси	scripts/deployment/gitea/git-push-gitea-via-proxy.sh

Полный справочник сервера: GITEA_COMPLETE_GUIDE.md.

---

Шаг 0: диагностика (2 минуты)

Из корня local_machine:

cd /Users/eternal/code/local_machine
git status
git remote -v
git branch -vv
git log -1 --oneline
git fetch origin 2>&1 | tail -5

Проверка	OK	Проблема
git status	на нужной ветке, осмысленные изменения	не в корне репо
origin	SSH 2223 или HTTPS gitea.hunab.app	нет remote → setup-and-push.sh
git fetch origin	без ошибки	сеть / auth → §2–§4
Gitea в браузере	https://gitea.hunab.app открывается	сеть / DNS → connectivity

SSH до Gitea (прямой):

ssh -o BatchMode=yes -o ConnectTimeout=10 -p 2223 -i ~/.ssh/hunab_deploy_key git@gitea.hunab.app
# ожидаем приветствие Gitea или "Hi there, ..." / exit 1 — не timeout

SSH через RU (как в proxy-скрипте):

ssh -o BatchMode=yes -o ConnectTimeout=8 hsites-ahau "echo RU_OK"
ssh -o BatchMode=yes -o ConnectTimeout=15 -p 2223 \
  -i ~/.ssh/hunab_deploy_key \
  -o ProxyJump=hsites-ahau \
  git@209.38.32.21 "echo GITEA_SSH_OK"

---

Правильные remote URL

Режим	URL
SSH (предпочтительно)	ssh://git@gitea.hunab.app:2223/hunabgit/local_machine.git
HTTPS	https://gitea.hunab.app/hunabgit/local_machine.git

Переключить:

git remote set-url origin ssh://git@gitea.hunab.app:2223/hunabgit/local_machine.git
# или
git remote set-url origin https://gitea.hunab.app/hunabgit/local_machine.git

Клонирование:

git clone ssh://git@gitea.hunab.app:2223/hunabgit/local_machine.git
# или
git clone https://gitea.hunab.app/hunabgit/local_machine.git

---

Симптом → причина → действие

1. Репозиторий ещё не на Gitea / «repository not found»

Причина: на сервере нет hunabgit/local_machine.

Действие:

1. https://gitea.hunab.app → New Repository → Name: local_machine → пустой (без README).
2. Или API: GITEA_TOKEN=… bash scripts/deployment/gitea/setup-and-push.sh --create-only
3. bash scripts/deployment/gitea/setup-and-push.sh или git push -u origin main

---

2. git push зависает / timeout (типично из РФ)

Причина: HTTPS или прямой SSH до DO режется или медленный маршрут.

Действие A — SSH на 2223:

git remote set-url origin ssh://git@gitea.hunab.app:2223/hunabgit/local_machine.git
GIT_SSH_COMMAND="ssh -i ~/.ssh/hunab_deploy_key -o ConnectTimeout=30" git push origin main

Действие B — скрипт через прокси (рекомендуется из РФ):

cd /Users/eternal/code/local_machine
bash scripts/deployment/gitea/git-push-gitea-via-proxy.sh --dry-run
bash scripts/deployment/gitea/git-push-gitea-via-proxy.sh

Скрипт по порядку: SSH через hsites-ahau → HTTPS (короткий timeout) → bundle (scp + docker exec gitea).

Переменные при необходимости:

PROXY_SERVER=hsites-ahau \
TARGET_SSH_KEY=~/.ssh/hunab_deploy_key \
GITEA_SERVER=206.189.35.205 \
bash scripts/deployment/gitea/git-push-gitea-via-proxy.sh main

---

3. Permission denied (publickey) / auth failed

Причина: неверный ключ или ключ не добавлен в Gitea / ~/.ssh/config.

Действие:

ssh-add -l
ls -la ~/.ssh/hunab_deploy_key ~/.ssh/id_ed25519
ssh -v -p 2223 -i ~/.ssh/hunab_deploy_key git@gitea.hunab.app 2>&1 | tail -20

• В Gitea: Settings → SSH / GPG Keys — публичный ключ с Mac.
• В ~/.ssh/config блок для gitea.hunab.app с IdentityFile ~/.ssh/hunab_deploy_key, Port 2223.
• Через прокси: ключ hunab_deploy_key на целевой хост, id_ed25519 до RU.

SSH recovery: PROXY_EMERGENCY.md.

---

4. rejected (non-fast-forward) / нужен pull

Причина: на Gitea есть коммиты, которых нет локально.

Действие:

git fetch origin
git log --oneline HEAD..origin/main   # что на сервере
git pull --rebase origin main         # или merge — по политике команды
git push origin main

Не делать git push --force на main без явного запроса.

---

5. Push прошёл, но в Gitea старый коммит (bundle)

Причина: использовался bundle; локальный origin/main не обновился.

Действие:

git fetch origin
git log -1 origin/main
git log -1 main

Если расходятся — повторить push или git fetch после успешного bundle (скрипт делает git update-ref при совпадении).

---

6. Случайно пытаюсь закоммитить секреты

Причина: .env, ключи, VPN .conf с приватными ключами.

Действие:

git status
git diff --cached

Не коммитить: ~/.config/joplin-webdav/env, *.pem, *.key, docs/connectivity/vpn/*.conf, temp/ с личными данными. См. корневой .gitignore.

Если уже в индексе: git reset HEAD <file>.

---

7. «Not a git repository» / push из не того каталога

Причина: команды не из /Users/eternal/code/local_machine.

cd /Users/eternal/code/local_machine
git rev-parse --show-toplevel

---

8. Нет интернета / RU недоступен

Push невозможен, пока не восстановлена сеть.

curl -sS --max-time 8 https://gitea.hunab.app
ssh -o ConnectTimeout=6 hsites-ahau "echo RU_OK"

Hotspot / Wi‑Fi: HOTSPOT_NETWORK_EMERGENCY.md.
Прокси RU→DO: ./scripts/vpn/exit-via-ru-do.sh — после базового интернета.

---

Процедуры

Ежедневный push (нормальная сеть)

cd /Users/eternal/code/local_machine
git status
git add -p   # или конкретные файлы
git commit -m "Кратко: зачем изменение."
git push origin main

Коммиты создавать только по запросу (локальная политика). Не пушить без явного согласия, если так принято в workflow.

---

Первый push новой машины

cd /Users/eternal/code/local_machine
git clone ssh://git@gitea.hunab.app:2223/hunabgit/local_machine.git
# или уже есть папка:
bash scripts/deployment/gitea/setup-and-push.sh

---

Push только через прокси (рабочий режим из РФ)

cd /Users/eternal/code/local_machine
git add … && git commit -m "…"
bash scripts/deployment/gitea/git-push-gitea-via-proxy.sh --dry-run
bash scripts/deployment/gitea/git-push-gitea-via-proxy.sh

--dry-run показывает число коммитов к отправке, ничего не меняет.

---

После смены hotspot / VPN

1. Проверить интернет и RU: ssh hsites-ahau "echo OK".
2. git fetch origin — если OK, обычный git push.
3. Если fetch/push timeout → git-push-gitea-via-proxy.sh.

---

Скрипты

Скрипт	Назначение
scripts/deployment/gitea/setup-and-push.sh	git init, remote, первый commit+push; --create-only + GITEA_TOKEN
scripts/deployment/gitea/git-push-gitea-via-proxy.sh	Push main: SSH→HTTPS→bundle; --dry-run [branch]

Безопасность proxy-скрипта: не делает reset --hard, не --force push; только обновляет origin/main после успеха.

---

.gitignore (напоминание)

Коммитить можно: docs/, scripts/, примеры конфигов без секретов.

Нельзя: .env, ключи, temp/ с дампами, личные CSV, VPN conf с ключами, ~/.config/* секреты.

---

Логи и отладка

GIT_TRACE=1 GIT_SSH_COMMAND="ssh -v" git push origin main 2>&1 | tail -50

Bundle-артефакты: temp/gitea-push-*.bundle (скрипт удаляет после успеха).

Gitea UI: Commits на https://gitea.hunab.app/hunabgit/local_machine/commits/branch/main

---

Связанные документы

Документ	Зачем
README.md	Оглавление apps/git
LOCAL_MACHINE_GITEA_SETUP.md	Первичная настройка
GITEA_COMPLETE_GUIDE.md	Сервер, SSL, bundle детали
PROXY_GUIDE.md	SSH config, hsites-ahau
PROXY_EMERGENCY.md	Восстановление SSH

---

История типовых инцидентов

Ситу	Симптом	Фикс
—	HTTPS push hang	SSH :2223 или git-push-gitea-via-proxy.sh
—	repository not found	Создать repo на Gitea UI
—	Permission denied	hunab_deploy_key в Gitea + SSH config
2026-03	Первый push local_machine	setup-and-push.sh

---

Проверка remote: git remote -v. Push из РФ: bash scripts/deployment/gitea/git-push-gitea-via-proxy.sh --dry-run.