<!-- Bothost docs | HTML: https://bothost.ru/docs/git-repository-access | Markdown: https://bothost.ru/docs/git-repository-access.md | Index: https://bothost.ru/llms.txt -->

# Подключение приватного репозитория в bothost.ru

**Публичные** репозитории в разделе «Git репозитории» добавлять не нужно: для них достаточно указать обычный HTTPS- или SSH-URL при создании бота, без токена и без этой формы. Ниже описано подключение **только приватных** репозиториев (токен, deploy key и т.п.).

**Источники иллюстраций**

- Скриншоты **дашборда Bothost** и **формы admin-repos** — материалы bothost.ru (см. разделы ниже).
- Скриншоты **интерфейса GitHub** (настройки, Developer settings, токены) **взяты из ответов** в теме Stack Overflow [git — Clone a private repository (GitHub)](https://stackoverflow.com/questions/2505096/clone-a-private-repository-github); изображения с хостинга Stack Exchange (`i.sstatic.net`). Пользовательский контент на Stack Overflow распространяется по лицензии [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) с указанием источника.

## Дашборд Bothost: куда нажать

В [личном кабинете](https://bothost.ru/) откройте раздел **Git репозитории** — фиолетовая кнопка с иконкой ветки в верхней панели (рядом с «Создать бота» и «Тикеты поддержки»). Оттуда настраивается привязка репозитория к боту.

---

![Дашборд Bothost: кнопка «Git репозитории» в верхнем меню](/docs/images/dashboard-git-repositories.png)

## Форма «Подключение приватного репозитория»

Откроется страница [**Подключение приватного репозитория**](https://bothost.ru/admin-repos.php): выберите способ доступа — **SSH (deploy key)** или **HTTPS** (логин/пароль или токен).

В блоке **«Подключить репозиторий»** заполните поля:

| Поле | Что указать |
|------|-------------|
| **URL репозитория** | SSH или HTTPS, например `git@github.com:org/repo.git` или `https://github.com/org/repo.git` |
| **Ветка** | Обычно `main` или `master` |
| **Способ доступа** | Для токена GitHub — **HTTPS (логин/пароль или токен)** |
| **Username (для HTTPS)** | Для GitHub с PAT часто **`x-access-token`**, для GitLab — **`oauth2`**, либо ваш логин |
| **Пароль/Токен** | Personal Access Token или пароль (если допускает хостинг) |

Нажмите **Сохранить**.

---

**Подсказки на странице:** для GitHub при использовании токена рекомендуется username `x-access-token`, для GitLab — `oauth2`. Если в конце URL нет суффикса `.git`, он может быть добавлен автоматически при сохранении.

![Страница подключения приватного репозитория (admin-repos)](/docs/images/admin-repos-connect.png)

## 🎯 Минимальные права для деплоя

Для деплоя бота из приватного репозитория клиенту нужно дать **только права на чтение (Read)**.

### GitHub

**Минимальные права:**
- ✅ **Read** (чтение кода) - достаточно для клонирования

**Заметка:** для приватного репозитория нельзя полагаться на URL вида `git://github.com/...` (только чтение по этому протоколу). Нужен **HTTPS с токеном** или **SSH**. Если у аккаунта включена **2FA**, при `git clone` по HTTPS вместо пароля используйте **Personal Access Token**.

**Как дать доступ:**

#### Вариант 1: Personal Access Token (рекомендуется)

**Создание classic-токена (Tokens (classic)) — пошагово:**

1. Откройте **Settings** профиля на GitHub:

![Settings — меню профиля GitHub](https://i.sstatic.net/3VrIs.png)

2. Внизу списка слева выберите **Developer settings**:

![Developer settings](https://i.sstatic.net/uDsJm.png)

3. **Personal access tokens** → **Tokens (classic)** → **Generate new token (classic)**:

![Personal access tokens — Generate new token](https://i.sstatic.net/QtFtT.png)

4. Укажите название, срок действия и отметьте **`repo`** (для приватных репозиториев без этой области клонирование не получится). Для только публичных репозиториев достаточно `public_repo`:

![Выбор scope repo](https://i.sstatic.net/3HshU.png)

5. Нажмите **Generate token**:

![Generate token](https://i.sstatic.net/Nxmr0.png)

6. **Сразу скопируйте токен** — полный текст потом может быть недоступен:

![Сгенерированный PAT](https://i.sstatic.net/9XEDY.png)

**Кратко (тот же путь текстом):** Settings → Developer settings → Personal access tokens → Tokens (classic) → Scopes: `repo` (приватные) или `public_repo` (публичные).

**Опционально — Fine-grained token** (узкие права, в том числе на один репозиторий): Settings → Developer settings → **Fine-grained tokens** → Generate new token. Для сценария «только чтение кода для деплоя» задайте **Repository access** и для выбранного репозитория право **Contents: Read-only**.

![Settings — вход в настройки](https://i.sstatic.net/3L5yG.png)

![Developer settings](https://i.sstatic.net/kSHhT.png)

![Fine-grained tokens](https://i.sstatic.net/meWTk.png)

![Generate new token](https://i.sstatic.net/s9VH8.png)

![Только выбранные репозитории](https://i.sstatic.net/nIx2P.png)

![Contents — Read-only](https://i.sstatic.net/nwuCK.png)

7. В Bothost при добавлении репозитория:
   - Тип: HTTPS
   - Username: `x-access-token` (автоматически)
   - Token: вставляется токен клиента

**Права токена:**
```
✅ repo (для приватных репозиториев)
   - repo:status
   - repo_deployment
   - public_repo
   - repo:invite
   - security_events
```

#### Вариант 2: Deploy Key (для одного репозитория)

1. На manager ноде сгенерировать SSH ключ:
   ```bash
   ssh-keygen -t ed25519 -C "bothost-deploy" -f ~/.ssh/bothost_deploy_key
   ```

2. Добавить публичный ключ в репозиторий:
   - Settings → Deploy keys → Add deploy key
   - Title: `Bothost Deploy`
   - Key: содержимое `~/.ssh/bothost_deploy_key.pub`
   - ✅ Allow write access: **НЕ включать** (только чтение)

**Права Deploy Key:**
- ✅ Read-only доступ к репозиторию
- ❌ Не может изменять код
- ❌ Не может создавать issues/pull requests

#### Вариант 3: GitHub App (для организации)

Для организаций можно создать GitHub App с минимальными правами:
- ✅ Contents: Read (чтение кода)
- ✅ Metadata: Read (метаданные)

---

### GitLab

**Минимальные права:**
- ✅ **Guest** или **Reporter** роль

**Как дать доступ:**

#### Вариант 1: Personal Access Token

Создайте **Personal Access Token** в GitLab:

- **User Settings** → **Access Tokens**
- **Scopes:** только `read_repository`

В Bothost при подключении репозитория укажите:

- Тип: **HTTPS**
- **Username:** `oauth2`
- **Token:** ваш токен

**Права токена:** достаточно scope `read_repository` (чтение репозитория, клонирование для деплоя).

#### Вариант 2: Deploy Token

1. В репозитории:
   - Settings → Repository → Deploy tokens
   - Name: `Bothost Deploy`
   - Scopes: только `read_repository`
   - Expires: по желанию

2. Использовать:
   - Username: из GitLab
   - Token: из GitLab

---

### Bitbucket

**Минимальные права:**
- ✅ **Read** доступ

**Как дать доступ:**

#### Personal Access Token

1. Клиент создает App Password:
   - Personal settings → App passwords
   - Permissions: только `Repositories: Read`

2. В Bothost:
   - Тип: HTTPS
   - Username: username клиента
   - Token: app password

---

## 🔒 Безопасность

### ✅ Что безопасно:

1. **Deploy Key (SSH)** - самый безопасный вариант
   - Привязан к одному репозиторию
   - Не может изменять код
   - Можно отозвать в любой момент

2. **Personal Access Token с минимальными правами**
   - Только чтение
   - Можно ограничить по времени
   - Можно отозвать

3. **Deploy Token (GitLab)**
   - Только для деплоя
   - Ограничен по времени
   - Минимальные права

### ❌ Что НЕ безопасно:

1. **Полный доступ к аккаунту**
   - Никогда не просите пароль от аккаунта
   - Не используйте токены с правами на запись

2. **Токены с правами на изменение кода**
   - Не нужны для деплоя
   - Риск компрометации

---

## 📝 Инструкция для клиента

### GitHub

Скриншоты интерфейса GitHub см. в разделе **«Вариант 1: Personal Access Token»** выше.

1. Перейти в Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Нажать "Generate new token (classic)"
3. Название: `Bothost Deploy`
4. Expiration: выбрать срок (рекомендуется 1 год)
5. Scopes: выбрать только `repo` (для приватных) или `public_repo` (для публичных)
6. Нажать "Generate token"
7. **Скопировать токен** (показывается только один раз!)
8. В Bothost при добавлении репозитория:
   - Вставить URL репозитория
   - Выбрать "Приватный репозиторий"
   - Вставить токен в поле "Token"

### GitLab

1. Перейти в User Settings → Access Tokens
2. Token name: `Bothost Deploy`
3. Expiration date: выбрать срок
4. Scopes: выбрать только `read_repository`
5. Нажать "Create personal access token"
6. **Скопировать токен**
7. В Bothost:
   - URL репозитория
   - Выбрать "Приватный репозиторий"
   - Вставить токен

---

## 🔄 Обновление токенов

Если токен истек или был скомпрометирован:

1. Клиент создает новый токен
2. В Bothost обновляет репозиторий:
   - Перейти в настройки репозитория
   - Обновить токен
   - Сохранить

3. Старый токен можно отозвать в настройках GitHub/GitLab

---

## ✅ Рекомендации

### Для клиента:

1. **Использовать отдельный токен для Bothost**
   - Не использовать основной токен аккаунта
   - Легче отозвать при необходимости

2. **Установить срок действия**
   - Не создавать токены без срока
   - Рекомендуется 1 год

3. **Минимальные права**
   - Только чтение кода
   - Не давать права на запись

### Для Bothost:

1. **Хранить токены в зашифрованном виде**
   - Использовать base64 кодирование (как сейчас)
   - Не логировать токены

2. **Использовать HTTPS вместо SSH**
   - Проще для клиентов
   - Не нужны SSH ключи на сервере

3. **Проверять доступность репозитория**
   - Валидировать токен перед сохранением
   - Показывать ошибки если токен неверный

---

## 🆘 Решение проблем

### Ошибка: "Repository not found" или "Authentication failed"

**Причины:**
1. Токен неверный или истек
2. Токен не имеет прав на репозиторий
3. Репозиторий удален или переименован

**Решение:**
1. Проверить токен в настройках GitHub/GitLab
2. Создать новый токен с правильными правами
3. Обновить токен в Bothost

### Ошибка: "Permission denied"

**Причины:**
1. Токен не имеет прав на чтение
2. Репозиторий приватный, но токен для публичных

**Решение:**
1. Создать токен с правами `repo` (для приватных)
2. Проверить что репозиторий доступен с этим токеном

---

## 📋 Чеклист для клиента

- [ ] Создан Personal Access Token
- [ ] Токен имеет только права на чтение (`repo` или `read_repository`)
- [ ] Установлен срок действия токена
- [ ] Токен скопирован и вставлен в Bothost
- [ ] Репозиторий успешно добавлен в Bothost
- [ ] Тестовый деплой прошел успешно