109 lines
3.0 KiB
Markdown
109 lines
3.0 KiB
Markdown
# 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 <repo>` | Grant read access to a repo |
|
|
| `revoke-access.sh <repo>` | 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.)
|