---
name: forgejo-instance-setup
description: Set up and work with a Forgejo instance from scratch. Use when creating accounts, configuring tea CLI, generating tokens, or setting up 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 from scratch.

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

### 2. Install `tea` CLI

**Linux (amd64):**
```bash
curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-amd64.tar.gz | tar xz -C /tmp
sudo mv /tmp/tea /usr/local/bin/
sudo chmod +x /usr/local/bin/tea
```

**Verify:**
```bash
tea --version
# Expected: Version: [1m0.12.0[0m  golang: 1.25.7  go-sdk: v0.23.2
```

### 3. Configure Login

1. Log in to Forgejo web UI → **Settings** → **Application**
2. Click **Add Access Token**
3. Fill in:
   - Token name: e.g., `tea-cli`
   - Scopes (minimum): `read:user`, `write:repository`
4. Copy the generated token

**Save to config (`~/.config/tea/config.yml`):**
```yaml
logins:
- name: <instance-name>
  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>
```

## Common Tasks

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

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

### Push Changes
```bash
git add .
git commit -m "Update"
git push origin main
```

## Troubleshooting

### Token Scope Errors
If you see `token does not have at least one of required scope(s)`:
1. Go to Forgejo → Settings → Application
2. Edit your token or create a new one
3. Add required scopes (see table below)

### Connection Timeouts
- Check instance reachability: `ping <instance>`
- Check TLS: `curl -v https://<instance>`
- Check API: `curl https://<instance>/api/v1/version`

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

## Scope Reference

| Scope | Description |
|-------|-------------|
| `read:user` | View user profile and followers |
| `write:repository` | Create, update, delete repositories |
| `read:repository` | Read repository contents (public) |

## Example Workflow

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

# 2. Clone locally
git clone https://<instance>/username/krallen-skills.git

# 3. Add content and push
cd krallen-skills
echo "# Krallen Skills" > README.md
git add .
git commit -m "Initial commit"
git push origin main
```

## References

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