From 46e37f167a41855fac0f4355debc165b4add58f9 Mon Sep 17 00:00:00 2001 From: delta-cloud-208e Date: Sat, 21 Feb 2026 14:53:49 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=80=D1=83=D1=81=D1=81=D0=BA=D0=B8?= =?UTF-8?q?=D0=B9=20README=20=D0=BA=D0=B0=D0=BA=20=D0=BE=D1=81=D0=BD=D0=BE?= =?UTF-8?q?=D0=B2=D0=BD=D0=BE=D0=B9,=20=D0=B0=D0=BD=D0=B3=D0=BB=D0=B8?= =?UTF-8?q?=D0=B9=D1=81=D0=BA=D0=B8=D0=B9=20=D0=B2=20README=5Fen.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- README.md | 150 ++++++++++++++++++++++++++++++++++----------------- README_en.md | 108 +++++++++++++++++++++++++++++++++++++ 2 files changed, 208 insertions(+), 50 deletions(-) create mode 100644 README_en.md diff --git a/README.md b/README.md index 0dba803..557346b 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,66 @@ # gitea-token-access -Scripts and documentation for setting up restricted read-only access to private Gitea repositories. +Скрипты и документация для настройки ограниченного read-only доступа к приватным репозиториям Gitea. -## Problem +## Зачем это нужно -You have private repos on a Gitea server and need to give automated tools (installers, CI/CD, scripts) read access — without exposing your admin credentials. +Есть приватные репо на Gitea-сервере. Нужно дать автоматическим инструментам (установщики, CI/CD, скрипты) доступ на чтение — без раскрытия админских учётных данных. -## Solution +## Схема -A three-layer scheme: +Трёхуровневая модель доступа: -1. **Owner account** — full admin access, owns all repos -2. **Reader account** — restricted "hobo" account with no admin rights, only sees repos where explicitly added as collaborator -3. **API token** — scoped to `read:repository`, can only read what the reader account can see +``` +Владелец (admin) + │ + ├── создаёт "бомж"-аккаунт (через Admin API) + ├── выдаёт доступ к конкретным репо (collaborator, read) + │ + v +Бомж-аккаунт (reader) + │ + ├── не имеет админ-прав + ├── видит только те репо, куда его добавили + │ + v +API-токен (scope: read:repository) + │ + ├── может только читать + ├── используется в скриптах/установщиках + └── при утечке — ротируем, админ-данные не раскрыты +``` -If the token leaks, revoke it and rotate — no admin credentials are exposed. - -## Quick Start +## Быстрый старт ```bash -# 1. Copy and fill in your config +# 1. Скопировать и заполнить конфиг cp config.example.ini config.ini nano config.ini -# 2. Create reader account and token +# 2. Создать бомж-аккаунт и токен bash scripts/setup-reader.sh -# 3. Grant access to a specific repo +# 3. Дать доступ к конкретному репо bash scripts/grant-access.sh my-private-repo -# 4. Verify it works +# 4. Проверить что всё работает bash scripts/test-access.sh my-private-repo ``` -## Scripts +## Скрипты -| Script | Description | -|--------|-------------| -| `setup-reader.sh` | Create reader account + API token | -| `grant-access.sh ` | Grant read access to a repo | -| `revoke-access.sh ` | Revoke access from a repo | -| `list-access.sh` | List all accessible repos | -| `rotate-token.sh` | Delete old token, create new one | -| `test-access.sh [repo]` | Verify token and access work | +| Скрипт | Описание | +|--------|----------| +| `setup-reader.sh` | Создать бомж-аккаунт + API-токен | +| `grant-access.sh ` | Выдать доступ на чтение к репо | +| `revoke-access.sh ` | Забрать доступ | +| `list-access.sh` | Показать все доступные репо | +| `rotate-token.sh` | Удалить старый токен, создать новый | +| `test-access.sh [repo]` | Проверить что токен и доступ работают | -## Configuration +## Конфигурация -Copy `config.example.ini` to `config.ini` and fill in your values: +Скопируйте `config.example.ini` в `config.ini` и заполните своими данными: ```ini [gitea] @@ -54,55 +68,91 @@ url = https://git.example.com api_url = https://git.example.com/api/v1 [owner] -username = admin-user -password = admin-password +username = ваш-админ +password = ваш-пароль [reader] -username = readonly-user -password = reader-password +username = reader-аккаунт +password = пароль-reader email = reader@noreply.local token_name = installer-readonly token_scope = read:repository ``` -The `config.ini` file is gitignored and will never be committed. +Файл `config.ini` добавлен в `.gitignore` и никогда не будет закоммичен. -## Using the Token +## Использование токена -### In scripts (curl) +### В скриптах (curl) ```bash -curl -H "Authorization: token YOUR_TOKEN" \ +curl -H "Authorization: token ВАШ_ТОКЕН" \ https://git.example.com/api/v1/repos/owner/repo/raw/file.txt ``` ### Git clone ```bash -git clone https://reader:YOUR_TOKEN@git.example.com/owner/repo.git +git clone https://reader:ВАШ_ТОКЕН@git.example.com/owner/repo.git ``` ### Git credential store ```bash -echo "https://reader:YOUR_TOKEN@git.example.com" >> ~/.git-credentials +echo "https://reader:ВАШ_ТОКЕН@git.example.com" >> ~/.git-credentials git config --global credential.helper store git clone https://git.example.com/owner/repo.git ``` -## Documentation +## FAQ -- [Architecture](docs/architecture.md) — how the owner/reader/token scheme works -- [Manual Setup](docs/manual-setup.md) — step-by-step curl commands -- [README (Russian)](README_ru.md) +### Что делать если токен утёк? -## Security Notes +```bash +bash scripts/rotate-token.sh +``` -- The token has `read:repository` scope only — it cannot write, delete, or access admin APIs -- Access is per-repo: the reader only sees repos where they are an explicit collaborator -- If the token is compromised: run `rotate-token.sh` to invalidate old token and create a new one -- `config.ini` contains credentials — it is gitignored and must never be committed +Старый токен будет удалён и перестанет работать. Новый будет записан в `config.ini`. Обновите токен во всех системах, которые его используют. -## Requirements +### Как дать доступ к новому репо? -- Gitea instance with API enabled -- Owner account with admin privileges -- `curl` and `bash` -- No external dependencies (no jq, python, etc.) +```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` +- Никаких внешних зависимостей diff --git a/README_en.md b/README_en.md new file mode 100644 index 0000000..d92a7c1 --- /dev/null +++ b/README_en.md @@ -0,0 +1,108 @@ +# gitea-token-access + +Scripts and documentation for setting up restricted read-only access to private Gitea repositories. + +## Problem + +You have private repos on a Gitea server and need to give automated tools (installers, CI/CD, scripts) read access — without exposing your admin credentials. + +## Solution + +A three-layer scheme: + +1. **Owner account** — full admin access, owns all repos +2. **Reader account** — restricted "hobo" account with no admin rights, only sees repos where explicitly added as collaborator +3. **API token** — scoped to `read:repository`, can only read what the reader account can see + +If the token leaks, revoke it and rotate — no admin credentials are exposed. + +## Quick Start + +```bash +# 1. Copy and fill in your config +cp config.example.ini config.ini +nano config.ini + +# 2. Create reader account and token +bash scripts/setup-reader.sh + +# 3. Grant access to a specific repo +bash scripts/grant-access.sh my-private-repo + +# 4. Verify it works +bash scripts/test-access.sh my-private-repo +``` + +## Scripts + +| Script | Description | +|--------|-------------| +| `setup-reader.sh` | Create reader account + API token | +| `grant-access.sh ` | Grant read access to a repo | +| `revoke-access.sh ` | Revoke access from a repo | +| `list-access.sh` | List all accessible repos | +| `rotate-token.sh` | Delete old token, create new one | +| `test-access.sh [repo]` | Verify token and access work | + +## Configuration + +Copy `config.example.ini` to `config.ini` and fill in your values: + +```ini +[gitea] +url = https://git.example.com +api_url = https://git.example.com/api/v1 + +[owner] +username = admin-user +password = admin-password + +[reader] +username = readonly-user +password = reader-password +email = reader@noreply.local +token_name = installer-readonly +token_scope = read:repository +``` + +The `config.ini` file is gitignored and will never be committed. + +## Using the Token + +### In scripts (curl) +```bash +curl -H "Authorization: token YOUR_TOKEN" \ + https://git.example.com/api/v1/repos/owner/repo/raw/file.txt +``` + +### Git clone +```bash +git clone https://reader:YOUR_TOKEN@git.example.com/owner/repo.git +``` + +### Git credential store +```bash +echo "https://reader:YOUR_TOKEN@git.example.com" >> ~/.git-credentials +git config --global credential.helper store +git clone https://git.example.com/owner/repo.git +``` + +## Documentation + +- [Architecture](docs/architecture.md) — how the owner/reader/token scheme works +- [Manual Setup](docs/manual-setup.md) — step-by-step curl commands +- [README (Russian)](README.md) + +## Security Notes + +- The token has `read:repository` scope only — it cannot write, delete, or access admin APIs +- Access is per-repo: the reader only sees repos where they are an explicit collaborator +- If the token is compromised: run `rotate-token.sh` to invalidate old token and create a new one +- `config.ini` contains credentials — it is gitignored and must never be committed + +## Requirements + +- Gitea instance with API enabled +- Owner account with admin privileges +- `curl` and `bash` +- No external dependencies (no jq, python, etc.)