refactor: restructure forgejo skill per Agent Skills spec
This commit is contained in:
parent
e10bf21b86
commit
c8b5c5457b
2 changed files with 145 additions and 218 deletions
|
|
@ -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: <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
|
|
||||||
```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
|
|
||||||
```
|
|
||||||
145
forgejo-instance-setup/SKILL.md
Normal file
145
forgejo-instance-setup/SKILL.md
Normal file
|
|
@ -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: <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/)
|
||||||
Loading…
Add table
Reference in a new issue