From c8b5c5457bc904b327b21adcf001feb40349025b Mon Sep 17 00:00:00 2001 From: Nazim Date: Thu, 16 Apr 2026 17:45:14 +0000 Subject: [PATCH] refactor: restructure forgejo skill per Agent Skills spec --- forgejo-instance-setup.md | 218 -------------------------------- forgejo-instance-setup/SKILL.md | 145 +++++++++++++++++++++ 2 files changed, 145 insertions(+), 218 deletions(-) delete mode 100644 forgejo-instance-setup.md create mode 100644 forgejo-instance-setup/SKILL.md diff --git a/forgejo-instance-setup.md b/forgejo-instance-setup.md deleted file mode 100644 index 14579ef..0000000 --- a/forgejo-instance-setup.md +++ /dev/null @@ -1,218 +0,0 @@ -# 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 -```bash -brew install tea-org/tea/tea -``` - -### Linux (amd64) -```bash -# 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) -```bash -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 -```bash -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 -```yaml -logins: -- name: vmd185580 - url: https://vmd185580.tailf38284.ts.net - token: - default: true - ssh_host: vmd185580.tailf38284.ts.net - ssh_key: "" - insecure: false - user: nazim - created: -preferences: - editor: false - flag_defaults: - remote: "" -``` - -#### Get Current Unix Timestamp -```bash -date +%s -# Example output: 1776359800 -``` - -### Test Connection -```bash -tea whoami -# Expected output: -# # nazim -# Follower Count: 0, Following Count: 0, Starred Repos: 0 -``` - -## 4. Common Tasks - -### List Logins -```bash -tea login list -``` - -### Create a Repository -```bash -tea repos create --name my-repo \ - --description "My project" \ - --init \ - --license mit -``` - -### Clone a Repository -```bash -tea clone nazim/my-repo -# or -git clone https://vmd185580.tailf38284.ts.net/nazim/my-repo.git -``` - -### List Repositories -```bash -tea repos list --mine -``` - -### Create an Issue -```bash -tea issues create --repo nazim/my-repo \ - --title "Bug: Something is wrong" \ - --body "Steps to reproduce..." -``` - -### Create a Pull Request -```bash -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 -```bash -ssh-keygen -t ed25519 -C "nazim@openclaw.ai" -f ~/.ssh/vmd185580 -``` - -### Add Public Key to Forgejo -```bash -cat ~/.ssh/vmd185580.pub -# Copy output to Forgejo → Settings → SSH Keys -``` - -### Configure Git SSH Host -```bash -# Add to ~/.ssh/config -Host vmd185580.tailf38284.ts.net - HostName vmd185580.tailf38284.ts.net - User git - Port 222 - IdentityFile ~/.ssh/vmd185580 -``` - -### Clone via SSH -```bash -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: -```bash -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 - -```bash -# 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 -``` diff --git a/forgejo-instance-setup/SKILL.md b/forgejo-instance-setup/SKILL.md new file mode 100644 index 0000000..ba9d8b9 --- /dev/null +++ b/forgejo-instance-setup/SKILL.md @@ -0,0 +1,145 @@ +--- +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: + url: https:// + token: + default: true + ssh_host: + user: + created: +``` + +**Test connection:** +```bash +tea whoami +# Expected output: # +``` + +## 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:@/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 ` +- Check TLS: `curl -v https://` +- Check API: `curl https:///api/v1/version` + +### Wrong Login Used +```bash +tea whoami --login +``` + +## 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:///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/)