krallen-skills/forgejo-instance-setup.md

Forgejo Instance Setup Guide

This document describes how to set up and work with a Forgejo instance from scratch.

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 (e.g., nazim)
   • Email address
   • Password
4. Complete CAPTCHA if required
5. Check email for verification link (if email is enabled)

Via API (Admin-only)

Regular users cannot create accounts via API. Contact an admin or use the web UI.

2. Install tea CLI

macOS

brew install tea-org/tea/tea

Linux (amd64)

# Download latest release
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

Linux (arm64)

curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-arm64.tar.gz | tar xz -C /tmp
sudo mv /tmp/tea /usr/local/bin/
sudo chmod +x /usr/local/bin/tea

Verify Installation

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

3. Configure Login

Get a Personal Access Token

1. Log in to your Forgejo instance via web UI
2. Go to Settings → Application
3. Click Add Access Token
4. Fill in:
   • Token name: e.g., tea-cli
   • Select scopes (minimum required):
     • read:user — View user profile
     • write:repository — Create and manage repos
   • Click Generate Token
5. Copy the generated token (you won't see it again!)

Save to tea Config

The config file is at:

• Linux/macOS: ~/.config/tea/config.yml
• Windows: %AppData%\tea\config.yml

Example Config

logins:
- name: vmd185580
  url: https://vmd185580.tailf38284.ts.net
  token: <your-generated-token-here>
  default: true
  ssh_host: vmd185580.tailf38284.ts.net
  ssh_key: ""
  insecure: false
  user: nazim
  created: <unix-timestamp>
preferences:
  editor: false
  flag_defaults:
    remote: ""

Get Current Unix Timestamp

date +%s
# Example output: 1776359800

Test Connection

tea whoami
# Expected output:
# # nazim                                                                     
# Follower Count: 0, Following Count: 0, Starred Repos: 0

4. Common Tasks

List Logins

tea login list

Create a Repository

tea repos create --name my-repo \
  --description "My project" \
  --init \
  --license mit

Clone a Repository

tea clone nazim/my-repo
# or
git clone https://vmd185580.tailf38284.ts.net/nazim/my-repo.git

List Repositories

tea repos list --mine

Create an Issue

tea issues create --repo nazim/my-repo \
  --title "Bug: Something is wrong" \
  --body "Steps to reproduce..."

Create a Pull Request

tea pr create --repo nazim/my-repo \
  --title "Fix: Something was wrong" \
  --body "This PR fixes the issue." \
  --head feature-branch

5. SSH Access (Optional)

If you want to use SSH instead of HTTPS:

Generate SSH Key

ssh-keygen -t ed25519 -C "nazim@openclaw.ai" -f ~/.ssh/vmd185580

Add Public Key to Forgejo

cat ~/.ssh/vmd185580.pub
# Copy output to Forgejo → Settings → SSH Keys

Configure Git SSH Host

# Add to ~/.ssh/config
Host vmd185580.tailf38284.ts.net
  HostName vmd185580.tailf38284.ts.net
  User git
  Port 222
  IdentityFile ~/.ssh/vmd185580

Clone via SSH

git clone ssh://git@vmd185580.tailf38284.ts.net:222/nazim/my-repo.git

6. Troubleshooting

Token Scope Errors

If you see token does not have at least one of required scope(s), add more scopes to your token via Forgejo web UI → Settings → Application.

Connection Timeouts

• Check if the instance is reachable: ping vmd185580.tailf38284.ts.net
• Check TLS: curl -v https://vmd185580.tailf38284.ts.net
• Check API: curl https://vmd185580.tailf38284.ts.net/api/v1/version

Wrong Login Used

Set the default login in config or use --login flag:

tea whoami --login vmd185580

7. Scope Reference

Scope	Description
read:user	View user profile and followers
write:repository	Create, update, delete repositories
read:repository	Read repository contents (public)
write:organization	Manage organizations
admin:org	Admin-level org access

8. Example Workflow

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

# 2. Clone locally
git clone https://vmd185580.tailf38284.ts.net/nazim/krallen-skills.git

# 3. Add content
cd krallen-skills
echo "# Krallen Skills" > README.md

# 4. Push changes
git add .
git commit -m "Initial commit"
git push origin main