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