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

# 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:

[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)

curl -H "Authorization: token YOUR_TOKEN" \
  https://git.example.com/api/v1/repos/owner/repo/raw/file.txt

Git clone

git clone https://reader:YOUR_TOKEN@git.example.com/owner/repo.git

Git credential store

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 — how the owner/reader/token scheme works
• Manual Setup — step-by-step curl commands
• README (Russian)

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