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

name	description
forgejo-instance-setup	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):

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:

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

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:

tea whoami
# Expected output: # <username>

Common Tasks

Create a Repository

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

Clone a Repository

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

Push Changes

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

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

# 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
• tea CLI GitHub
• Gitea API Docs