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](../../git/GITEA_COMPLETE_GUIDE.md).

---

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

Из корня **local_machine**:

```bash
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 (прямой):**

```bash
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-скрипте):**

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

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

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

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

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

```bash
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 — скрипт через прокси (рекомендуется из РФ):**

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

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

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

**Действие:**

```bash
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](../../connectivity/PROXY_EMERGENCY.md).

---

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

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

**Действие:**

```bash
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` не обновился.

**Действие:**

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

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

---

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

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

**Действие:**

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

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

---

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

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

```bash
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](../../connectivity/HOTSPOT_NETWORK_EMERGENCY.md).  
Прокси RU→DO: `./scripts/vpn/exit-via-ru-do.sh` — **после** базового интернета.

---

## Процедуры

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

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

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

---

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

```bash
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 только через прокси (рабочий режим из РФ)

```bash
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/*` секреты.

---

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

```bash
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](./README.md) | Оглавление apps/git |
| [LOCAL_MACHINE_GITEA_SETUP.md](../../git/LOCAL_MACHINE_GITEA_SETUP.md) | Первичная настройка |
| [GITEA_COMPLETE_GUIDE.md](../../git/GITEA_COMPLETE_GUIDE.md) | Сервер, SSL, bundle детали |
| [PROXY_GUIDE.md](../../connectivity/PROXY_GUIDE.md) | SSH config, hsites-ahau |
| [PROXY_EMERGENCY.md](../../connectivity/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`.*