# gitea-token-access

Скрипты и документация для настройки ограниченного read-only доступа к приватным репозиториям Gitea.

## Зачем это нужно

Есть приватные репо на Gitea-сервере. Нужно дать автоматическим инструментам (установщики, CI/CD, скрипты) доступ на чтение — без раскрытия админских учётных данных.

## Схема

Трёхуровневая модель доступа:

```
Владелец (admin)
    │
    ├── создаёт "бомж"-аккаунт (через Admin API)
    ├── выдаёт доступ к конкретным репо (collaborator, read)
    │
    v
Бомж-аккаунт (reader)
    │
    ├── не имеет админ-прав
    ├── видит только те репо, куда его добавили
    │
    v
API-токен (scope: read:repository)
    │
    ├── может только читать
    ├── используется в скриптах/установщиках
    └── при утечке — ротируем, админ-данные не раскрыты
```

## Быстрый старт

```bash
# 1. Скопировать и заполнить конфиг
cp config.example.ini config.ini
nano config.ini

# 2. Создать бомж-аккаунт и токен
bash scripts/setup-reader.sh

# 3. Дать доступ к конкретному репо
bash scripts/grant-access.sh my-private-repo

# 4. Проверить что всё работает
bash scripts/test-access.sh my-private-repo
```

## Скрипты

| Скрипт | Описание |
|--------|----------|
| `setup-reader.sh` | Создать бомж-аккаунт + API-токен |
| `grant-access.sh <repo>` | Выдать доступ на чтение к репо |
| `revoke-access.sh <repo>` | Забрать доступ |
| `list-access.sh` | Показать все доступные репо |
| `rotate-token.sh` | Удалить старый токен, создать новый |
| `test-access.sh [repo]` | Проверить что токен и доступ работают |

## Конфигурация

Скопируйте `config.example.ini` в `config.ini` и заполните своими данными:

```ini
[gitea]
url = https://git.example.com
api_url = https://git.example.com/api/v1

[owner]
username = ваш-админ
password = ваш-пароль

[reader]
username = reader-аккаунт
password = пароль-reader
email = reader@noreply.local
token_name = installer-readonly
token_scope = read:repository
```

Файл `config.ini` добавлен в `.gitignore` и никогда не будет закоммичен.

## Использование токена

### В скриптах (curl)
```bash
curl -H "Authorization: token ВАШ_ТОКЕН" \
  https://git.example.com/api/v1/repos/owner/repo/raw/file.txt
```

### Git clone
```bash
git clone https://reader:ВАШ_ТОКЕН@git.example.com/owner/repo.git
```

### Git credential store
```bash
echo "https://reader:ВАШ_ТОКЕН@git.example.com" >> ~/.git-credentials
git config --global credential.helper store
git clone https://git.example.com/owner/repo.git
```

## FAQ

### Что делать если токен утёк?

```bash
bash scripts/rotate-token.sh
```

Старый токен будет удалён и перестанет работать. Новый будет записан в `config.ini`. Обновите токен во всех системах, которые его используют.

### Как дать доступ к новому репо?

```bash
bash scripts/grant-access.sh имя-нового-репо
```

### Как убрать доступ к репо?

```bash
bash scripts/revoke-access.sh имя-репо
```

### Как посмотреть к чему есть доступ?

```bash
bash scripts/list-access.sh
```

### Можно ли использовать для другого Gitea-сервера?

Да. Просто измените `url` и `api_url` в `config.ini`. Скрипты универсальны и работают с любым Gitea-инстансом.

### Нужен ли jq или python?

Нет. Скрипты используют только `bash`, `curl`, `grep`, `sed` — стандартные утилиты Linux.

## Документация

- [Архитектура](docs/architecture.md) — схема владелец/бомж/токен
- [Ручная настройка](docs/manual-setup.md) — пошаговые curl-команды
- [README (English)](README_en.md)

## Безопасность

- Токен имеет scope `read:repository` — не может писать, удалять или использовать админ API
- Доступ гранулярный: бомж видит только те репо, где он явно добавлен как collaborator
- При компрометации токена: запустите `rotate-token.sh`
- `config.ini` содержит учётные данные — он в `.gitignore` и не коммитится

## Требования

- Gitea-инстанс с включённым API
- Аккаунт владельца с правами администратора
- `curl` и `bash`
- Никаких внешних зависимостей