krallen-skills/forgejo-instance-setup/SKILL.md

---
name: forgejo-instance-setup
description: Set up and work with a Forgejo instance from scratch. Includes registration, tea CLI, docker/container paths, API automation, token management, and repository workflows on self-hosted Forgejo/Gitea instances.
---

# Forgejo Instance Setup Skill

This skill provides step-by-step guidance for setting up and working with a Forgejo instance.

## Directory Structure

```
forgejo-instance-setup/
├── SKILL.md           # This file — main instructions
├── scripts/           # Helper scripts (optional)
├── references/        # Detailed reference docs
└── assets/            # Templates and resources
```

## Quick Start

### 1. Create an Account

**Via Web UI (recommended for humans):**
1. Go to your Forgejo instance URL (e.g., `https://vmd185580.tailf38284.ts.net`)
2. Click **Sign Up** or **Register**
3. Fill in username, email, password
4. Complete CAPTCHA if required

> **Note:** Regular users cannot create accounts via API — use the web UI.  
> **New instance?** Admin may need to approve/activate your account first. Check if you can log in after registering.

**Via Web UI programmatically (for agents/bots):**
```bash
# Fetch CSRF token and submit registration
CSRF=$(curl -s -c cookies.txt https://<instance>/user/sign_up | \
  grep -oP 'value="\K[^"]+' | head -1)

curl -s -c cookies.txt -b cookies.txt \
  -X POST https://<instance>/user/sign_up \
  -H "x-csrf-token: $CSRF" \
  --data-urlencode "_csrf=$CSRF" \
  --data-urlencode "user_name=my-bot" \
  --data-urlencode "email=bot@example.com" \
  --data-urlencode "password=<strong-password>" \
  --data-urlencode "retype=<strong-password>"
# Expect redirect or flash-message. "already taken" → account exists.
```

### 2. Install `tea` CLI

**Option A — Standard install (with sudo):**
```bash
# Detect latest version
VERSION=$(curl -s https://dl.gitea.com/tea/ | grep -oP 'href="\K[\d.]+(?=/")' | sort -V | tail -1)
curl -sL -o /usr/local/bin/tea "https://dl.gitea.com/tea/$VERSION/tea-${VERSION}-linux-amd64"
chmod +x /usr/local/bin/tea
```

**Option B — No sudo (containers, CI):**
```bash
VERSION=$(curl -s https://dl.gitea.com/tea/ | grep -oP 'href="\K[\d.]+(?=/")' | sort -V | tail -1)
mkdir -p ~/.local/bin
curl -sL -o ~/.local/bin/tea "https://dl.gitea.com/tea/$VERSION/tea-${VERSION}-linux-amd64"
chmod +x ~/.local/bin/tea
# Ensure ~/.local/bin is in PATH
```

**Verify:**
```bash
tea --version
# Example output: Version: [1m0.14.1[0m  golang: 1.26.3  go-sdk: v0.25.1
```

### 3. Generate an Access Token

1. Log in to Forgejo web UI → **Settings** → **Applications**
2. Under **Access Tokens**, enter a name (e.g., `tea-cli`)
3. Select scopes — **recommended:**
   - `all` — simplest for autonomous agents
   - Or minimal: `read:user`, `write:repository`, `write:issue`
4. Click **Generate Token**
5. **Copy the token immediately** — it is shown only once!

**Programmatic token creation (after login):**
```python
import urllib.request, urllib.parse, http.cookiejar, re

cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))

# 1. Login
resp = opener.open("https://<instance>/user/login")
csrf = re.search(r'value="([^"]+)"', resp.read().decode()).group(1)
data = urllib.parse.urlencode({"_csrf": csrf, "user_name": "my-bot", "password": "<pw>"}).encode()
req = urllib.request.Request("https://<instance>/user/login", data=data, method='POST')
req.add_header("Content-Type", "application/x-www-form-urlencoded")
opener.open(req)

# 2. Create token
resp2 = opener.open("https://<instance>/user/settings/applications")
csrf2 = re.search(r'value="([^"]+)"', resp2.read().decode()).group(1)
data2 = urllib.parse.urlencode({"_csrf": csrf2, "name": "tea-cli", "scope": "all"}).encode()
req2 = urllib.request.Request("https://<instance>/user/settings/applications", data=data2, method='POST')
req2.add_header("Content-Type", "application/x-www-form-urlencoded")
resp3 = opener.open(req2)
html3 = resp3.read().decode()
token = re.search(r'Your new token[^<]*<strong>([^<]+)</strong>', html3)
if token: print(f"TOKEN: {token.group(1)}")
```

### 4. Configure `tea`

**Save to `~/.config/tea/config.yml`:**
```yaml
logins:
- name: botreasury
  url: https://<your-forgejo-instance>
  token: <your-token-here>
  default: true
  ssh_host: <your-forgejo-instance>
  user: <username>
  created: <unix-timestamp>
```

**Test connection:**
```bash
tea whoami
# Expected output: # <username>
```

### 5. Set Up Git (Required!)

Git needs your identity before you can commit:
```bash
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
```

Optional: set `main` as default branch name:
```bash
git config --global init.defaultBranch main
```

## Common Tasks

### Create a Repository
```bash
# Create on Forgejo
tea repos create --name my-repo \
  --description "My project"

# Clone and init locally (creates "main" branch)
git clone https://<username>:<token>@<instance>/<username>/my-repo.git
cd my-repo
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main
```

**Alternative — local-first, then push:**
```bash
mkdir my-repo && cd my-repo
git init --initial-branch main   # or: git init && git branch -m master main
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
tea repos create --name my-repo --description "My project"
git remote add origin https://<username>:<token>@<instance>/<username>/my-repo.git
git push -u origin main
```

### Clone a Repository
```bash
tea clone username/my-repo
# or with token URL:
git clone https://username:<token>@<instance>/username/my-repo.git
```

### Push Changes
```bash
git add .
git commit -m "Describe your change"
git push origin main
```

### Fork and PR
```bash
# Create a fork via API
curl -s -X POST \
  -H "Authorization: token <your-token>" \
  -H "Content-Type: application/json" \
  "https://<instance>/api/v1/repos/<owner>/<repo>/forks" \
  -d '{}'

# Clone your fork, make changes, push
git clone https://<username>:<token>@<instance>/<username>/<repo>.git
cd <repo>
# make changes, commit, push

# Create a pull request via tea
tea pulls create --repo <owner>/<repo> \
  --title "Your PR title" \
  --description "Description of your changes" \
  --head <username>:<branch> \
  --base main

# Or via API
curl -s -X POST \
  -H "Authorization: token <your-token>" \
  "https://<instance>/api/v1/repos/<owner>/<repo>/pulls" \
  -d '{"title":"PR title","body":"PR body","head":"<username>:<branch>","base":"main"}'
```

## Troubleshooting

### Token Scope Errors
`token does not have at least one of required scope(s)`:
1. Go to Forgejo → Settings → Application
2. Generate a new token with required scopes (easiest: `all`)
3. Update `~/.config/tea/config.yml` with the new token

### Suspended / Inactive Account
- Self-hosted: admin needs to activate your account on the server
- `sudo -u git /app/gitea/gitea admin user activate --username <user>`

### No `sudo` Available
Install to `~/.local/bin/` instead of `/usr/local/bin/`

### `git push` Fails With `src refspec main does not match any`
Your local branch is likely named `master`. Fix:
```bash
git branch -m master main
git push -u origin main
```
To prevent this: `git config --global init.defaultBranch main`

### Connection Timeouts
- Check instance reachability: `curl -sI https://<instance>`
- Check API: `curl -s https://<instance>/api/v1/version`
- Tailscale/ZeroTier required? Ensure the agent is on the same network.

### Wrong Login Used
```bash
tea whoami --login <instance-name>
```

### Token Not Found in Response
The token is only shown **once** after generation. If you lost it:
1. Delete the old token in Settings → Applications
2. Create a new one

## Scope Reference

| Scope | Description |
|-------|-------------|
| `all` | Full access (easiest for bots/agents) |
| `read:user` | View user profile and followers |
| `write:repository` | Create, update, delete repositories |
| `read:repository` | Read repository contents |
| `write:issue` | Create and manage issues |

## Example Workflow — Full Round Trip

```bash
# 1. Git identity
git config --global user.name "Agent Bot"
git config --global user.email "agent@example.com"
git config --global init.defaultBranch main

# 2. Create repo
tea repos create --name krallen-skills \
  --description "Forgejo instance skills" \
  --init

# 3. Clone
git clone https://<instance>/<username>/krallen-skills.git
cd krallen-skills

# 4. Add content
echo "# Krallen Skills" > README.md
git add .
git commit -m "Initial commit"
git push origin main

# 5. Later: fork upstream and PR
curl -s -X POST -H "Authorization: token <token>" \
  "https://<instance>/api/v1/repos/upstream/repo/forks" -d '{}'
git clone https://<token>@<instance>/<username>/repo.git
# make changes, commit, push
curl -s -X POST -H "Authorization: token <token>" \
  "https://<instance>/api/v1/repos/upstream/repo/pulls" \
  -d '{"title":"Improve X","head":"<username>:<branch>","base":"main"}'
```

## References

- [Forgejo Documentation](https://forgejo.org/docs/)
- [tea CLI Downloads](https://dl.gitea.com/tea/)
- [Gitea/Forgejo API Docs](https://docs.gitea.com/next/api/)