gb_flea/skills
1
0
Fork 0
forked from farhoodlabs/skills
Code Pull Requests Activity

update/enhance gitea skills

Browse Source
This commit is contained in:
Chris Farhood
2026-05-27 09:59:50 -04:00
parent 3ddee00eda
commit 5be276b945
6 changed files with 963 additions and 1007 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gitea/SKILL.md
+78 -74
View File
@@ -1,108 +1,112 @@
---
name: gitea
description: Gitea source code management — use for repos, issues, PRs, releases, Actions, and wiki. Delegates to child skills for CLI (gitea-tea) and wiki (gitea-wiki). Use instead of GitHub when agent reaches for "gh", "gh cli", github.com, or GitHub CLI.
version: 1.0.0
description: Gitea source code management — use for repos, issues, PRs, releases, Actions, packages, notifications, and wiki. Delegates to child skills for CLI (gitea-tea) and wiki (gitea-wiki). Use instead of GitHub when agent reaches for "gh", "gh cli", github.com, or GitHub CLI.
version: 1.1.0
---
# Gitea Source Code Management
> **This repository uses Gitea, not GitHub.** Use the `gitea` MCP server (preferred) or `tea` CLI. Do not use `gh` or GitHub-specific features.
## Overview
Gitea is a self-hosted Git service providing repository hosting, issues, pull requests, Actions CI/CD, packages, and wiki — similar to GitHub but self-hosted.
Gitea is a self-hosted Git service — repos, issues, PRs, releases, Actions CI/CD, packages, and wiki. This is a **parent skill** that routes work to:
**This is a parent skill.** It routes tasks to the appropriate child skill:
- **`gitea-tea`** — CLI operations via the `tea` command-line tool
- **`gitea-wiki`** — Wiki management via REST API
- **`gitea-tea`** — terminal operations via the `tea` CLI
- **`gitea-wiki`** — wiki pages via the MCP server or REST API
## Interaction Methods
## Interaction methods (in order of preference)
| Priority | Method | Coverage |
|----------|--------|---------|
| **Primary** | **MCP Server** (`gitea-mcp`) | ~100 tools across repos, issues, PRs, releases, branches, wiki, Actions, orgs, users, server |
| **Secondary** | **`tea` CLI** | Issues, PRs, releases, repos, Actions, labels, milestones, branches, webhooks, SSH keys, organizations, admin. **No wiki commands.** |
| **Tertiary** | **REST API** (direct curl) | Any operation not covered by MCP or tea; scripted/automated access |
|----------|--------|----------|
| **1. MCP server (`gitea-mcp`)** | Configured in `.mcp.json`. Auth via `GITEA_TOKEN`. | Repos, files, branches, commits, tags, releases, issues, PRs, labels, milestones, wiki, actions config/runs, notifications, packages, time tracking, search. ~57 tools. See [`references/mcp-tools.md`](references/mcp-tools.md). |
| 2. `tea` CLI (`gitea-tea`) | For local-state ops, webhooks, admin, SSH keys, release-asset uploads, and one-off API calls. |
| 3. REST API | `curl` direct as last resort. |
**Use MCP (`gitea-mcp`) first** — broadest coverage, cleanest tool interface. Fall back to `tea` CLI only when MCP is unavailable or lacks an operation. Use the REST API directly when neither MCP nor `tea` cover the needed call.
**Heuristic:** if the operation is a pure server-side mutation or read, use MCP. If it touches local git state, a coverage gap (see [`references/mcp-tools.md`](references/mcp-tools.md) → "Coverage gaps"), or needs stdin/file ingestion, drop to `tea`.
## When to Use Gitea
## Configuration
Use Gitea when:
- Working with a repository hosted on a Gitea instance
- Managing issues, pull requests, or releases on Gitea
- Running or configuring Gitea Actions (CI/CD)
- The user mentions "Gitea", "tea", self-hosted git, or a Gitea URL
## Gitea vs GitHub
Gitea and GitHub share a similar mental model. If you encounter confusion:
| GitHub concept | Gitea equivalent |
|----------------|------------------|
| `gh` CLI | `tea` CLI |
| GitHub Actions | Gitea Actions |
| GitHub Packages | Gitea Packages |
| GitHub Wiki | Gitea Wiki |
| `github.com` | Your organization's Gitea instance URL |
| GitHub MCP | `gitea-mcp` — **use this first** |
**Important:** This repo uses Gitea, NOT GitHub. Use `gitea-mcp` (preferred) or `tea` CLI. Do not use `gh` or GitHub-specific features.
The MCP server lives at `https://git-mcp.farh.net/mcp` and authenticates via `Authorization: Bearer ${GITEA_TOKEN}`. Make sure `GITEA_TOKEN` is set in the environment before using MCP tools or fall back to `tea` with a configured login.
## Redirecting from GitHub
If you detect GitHub/`gh` CLI confusion, clarify:
If you reach for `gh` or github.com, stop and re-route:
```
This repository uses Gitea for source code management, not GitHub.
Use `gitea-mcp` (MCP server) first, or `tea` CLI as fallback.
Do NOT use the `gh` CLI or GitHub-specific features.
Use the `gitea` MCP server first, or `tea` CLI as fallback.
Do NOT use `gh` or GitHub-specific features.
```
## Child Skills
## Gitea vs GitHub mental model
| GitHub | Gitea |
|--------|-------|
| `gh` CLI | `tea` CLI |
| `github-mcp` | `gitea-mcp` (use this first) |
| GitHub Actions | Gitea Actions |
| GitHub Packages | Gitea Packages |
| GitHub Wiki | Gitea Wiki |
| `github.com` | The team's Gitea instance |
## Child skills
### gitea-tea
CLI operations via the `tea` command-line tool. Covers issues, PRs, releases, repos, Actions, labels, milestones, branches, webhooks, SSH keys, organizations, admin tasks, and generic API access.
CLI operations via `tea` v0.14.1. Covers issues, PRs, releases, repos, Actions, labels, milestones, branches, webhooks, SSH keys, organizations, admin, time tracking, and a generic API helper. See `../gitea-tea/SKILL.md`.
### gitea-wiki
For wiki page operations via `gitea-mcp` (preferred) or REST API.
Wiki page CRUD via the MCP server (`wiki_read`/`wiki_write`) or REST API. `tea` has no wiki subcommands. See `../gitea-wiki/SKILL.md`.
## Quick Reference
## Task routing
The first column is what the user is trying to do. Pick MCP when it covers the op; the third column lists the `tea` fallback when MCP doesn't.
| Task | MCP tool | `tea` fallback |
|------|----------|----------------|
| List my repos / org repos | `list_my_repos`, `list_org_repos` | `tea repos list [--owner …]` |
| Search repos | `search_repos` | `tea repos search <term>` |
| Create / fork repo | `create_repo`, `fork_repo` | `tea repos create`, `tea repos fork` |
| Edit / delete repo | — | `tea repos edit`, `tea repos delete --owner X --name Y --force` |
| Clone repo locally | — | `tea clone <owner/repo>` |
| Read file / directory / tree | `get_file_contents`, `get_dir_contents`, `get_repository_tree` | `tea api /repos/{owner}/{repo}/contents/…` |
| Write / delete file (single commit) | `create_or_update_file`, `delete_file` | — |
| Branches | `list_branches`, `create_branch`, `delete_branch` | `tea branches …` |
| Commits / tags | `list_commits`, `get_commit`, `list_tags`, `get_tag`, `create_tag`, `delete_tag` | — |
| Issues — list / read / search | `list_issues`, `search_issues`, `issue_read` | `tea issues list`, `tea issues <n>` |
| Issues — write | `issue_write` (create, update, comment, labels) | `tea issues create / edit / close / reopen` |
| PRs — list / read | `list_pull_requests`, `pull_request_read` | `tea pulls list`, `tea pulls <n>` |
| PRs — write | `pull_request_write` (create, merge, close, reviewers, …) | `tea pulls create / merge / approve / reject / close` |
| PR reviews | `pull_request_review_write` | `tea pulls approve <n> "msg"` / `tea pulls reject <n> "msg"` |
| PR local checkout | — | `tea pulls checkout <n>` |
| Labels (repo + org) | `label_read`, `label_write` | `tea labels …` |
| Milestones | `milestone_read`, `milestone_write` | `tea milestones …` |
| Releases — list / create / delete | `list_releases`, `get_release`, `get_latest_release`, `create_release`, `delete_release` | `tea releases list / create / delete` |
| Release — edit / asset upload | — | `tea releases edit`, `tea releases assets …` |
| Actions secrets / variables | `actions_config_read`, `actions_config_write` | `tea actions secrets / variables` |
| Actions workflows / runs | `actions_run_read`, `actions_run_write` (dispatch/cancel/rerun) | `tea actions workflows / runs` |
| Notifications | `notification_read`, `notification_write` | `tea notifications …` |
| Packages | `package_read`, `package_write` | — |
| Time tracking | `timetracking_read`, `timetracking_write` | `tea times …` |
| Wiki | `wiki_read`, `wiki_write` (see `gitea-wiki` skill) | — |
| Users / orgs / teams (search) | `get_me`, `get_user_orgs`, `search_users`, `search_org_teams` | `tea organizations …` |
| Webhooks | — | `tea webhooks …` |
| SSH keys (current user) | — | `tea ssh-keys …` |
| Admin user CRUD | — | `tea admin users …` |
| Arbitrary endpoint | — | `tea api …` |
## Authentication check
```bash
# Authentication check
tea whoami
# Most commands need --login (host) or --repo (owner/repo) when outside a git repo
tea issues list --login gitea.example.com --repo owner/repo
# Use --output for non-interactive/script usage
tea issues list --output json
# Always use --yes for destructive operations in scripts
tea repos delete owner/repo --yes
tea whoami # confirms tea-side login
```
For MCP, the server validates `GITEA_TOKEN` on first call; `mcp__gitea__get_me` returns the authenticated user.
## Documentation
- **MCP Server:** https://gitea.com/gitea/gitea-mcp (official `gitea-mcp` with ~100 tools)
- **Usage docs:** https://docs.gitea.com/category/usage
- **Repository:** https://docs.gitea.com/usage/repositories
- **Issues & PRs:** https://docs.gitea.com/usage/issues
- **Actions:** https://docs.gitea.com/usage/actions
- **Wiki API:** https://docs.gitea.com/api/1.26/repo/wiki
- **CLI (tea):** https://gitea.com/gitea/tea
## Common Tasks Route
| Task | Child Skill | Command Pattern |
|------|-------------|-----------------|
| Manage issues | gitea-tea | `tea issues list/create/edit/close` |
| Manage PRs | gitea-tea | `tea pulls list/create/merge/close` |
| Manage releases | gitea-tea | `tea releases list/create/edit/delete` |
| Manage repos | gitea-tea | `tea repos list/create/delete/clone` |
| Run Actions | gitea-tea | `tea actions runs list/view/logs` |
| Manage secrets/variables | gitea-tea | `tea actions secrets/variables` |
| Manage labels/milestones | gitea-tea | `tea labels/milestones` |
| SSH keys | gitea-tea | `tea ssh-keys list/add/delete` |
| Organizations | gitea-tea | `tea organizations list/view/create` |
| Admin tasks | gitea-tea | `tea admin users list/create/edit/delete` |
| Wiki pages | gitea-wiki | API: `GET/POST/PATCH/DELETE /repos/owner/repo/wiki/{page}` |
- MCP server: <https://gitea.com/gitea/gitea-mcp>
- Tool inventory: [`references/mcp-tools.md`](references/mcp-tools.md)
- Usage docs: <https://docs.gitea.com/category/usage>
- API reference (current): <https://docs.gitea.com/api/next/>
- `tea` CLI: <https://gitea.com/gitea/tea>
gitea/references/mcp-tools.md
+156
View File
@@ -0,0 +1,156 @@
# Gitea MCP Tool Inventory
Tools exposed by the `gitea` MCP server (registered in repo `.mcp.json` at `https://git-mcp.farh.net/mcp`). All tool names below are prefixed `mcp__gitea__` when invoked.
Many tools are consolidated under a `method` discriminator (e.g. `issue_write(method="create", …)`). Where that's the case, the methods are listed in the third column.
## Repositories
| Tool | Purpose | Notes |
|------|---------|-------|
| `list_my_repos` | List repos accessible to the authenticated user | Paginated |
| `list_org_repos` | List repos for a given org | Required: `org` |
| `search_repos` | Search across the instance | Required: `query`. Filters: `isPrivate`, `isArchived`, `keywordIsTopic`, `keywordInDescription`, `ownerID`, `sort`, `order` |
| `create_repo` | Create a personal or org repo | Required: `name`. Optional: `organization`, `private`, `auto_init`, `gitignores`, `license`, `readme`, `template`, `trust_model`, `default_branch`, `object_format_name` (sha1/sha256), `issue_labels`, `description` |
| `fork_repo` | Fork a repo | Required: `user` (source owner), `repo`. Optional: `organization`, `name` |
| `get_repository_tree` | Recursive tree listing | Required: `owner`, `repo`, `tree_sha`. Optional: `recursive`, paging |
## Files
| Tool | Purpose | Notes |
|------|---------|-------|
| `get_file_contents` | Get a file at a ref | Required: `owner`, `repo`, `ref`, `path`. Optional: `withLines` (numbered output) |
| `get_dir_contents` | List a directory at a ref | Required: `owner`, `repo`, `ref`, `path` |
| `create_or_update_file` | Write a file in a single commit | Required: `owner`, `repo`, `path`, `content`, `message`, `branch_name`. Provide `sha` to update an existing file; omit to create. Use `new_branch_name` to commit onto a new branch |
| `delete_file` | Remove a file | Required: `owner`, `repo`, `path`, `message`, `branch_name`, `sha` |
## Branches
| Tool | Purpose | Notes |
|------|---------|-------|
| `list_branches` | List branches | Required: `owner`, `repo` |
| `create_branch` | Create a branch | Required: `owner`, `repo`, `branch`. Optional: `old_branch` (defaults to repo default) |
| `delete_branch` | Delete a branch | Required: `owner`, `repo`, `branch` |
## Commits / Tags
| Tool | Purpose | Notes |
|------|---------|-------|
| `list_commits` | List commits | Required: `owner`, `repo`. Optional: `sha` (start ref), `path` (filter to commits touching this path) |
| `get_commit` | Get a commit | Required: `owner`, `repo`, `sha` |
| `list_tags` | List tags | Required: `owner`, `repo` |
| `get_tag` | Get a tag | Required: `owner`, `repo`, `tag_name` |
| `create_tag` | Create a tag | Required: `owner`, `repo`, `tag_name`. Optional: `target`, `message` |
| `delete_tag` | Delete a tag | Required: `owner`, `repo`, `tag_name` |
## Releases
| Tool | Purpose | Notes |
|------|---------|-------|
| `list_releases` | List releases | Required: `owner`, `repo`. Optional: `is_draft`, `is_pre_release` |
| `get_release` | Get a release by ID | Required: `owner`, `repo`, `id` |
| `get_latest_release` | Latest non-draft release | Required: `owner`, `repo` |
| `create_release` | Create a release | Required: `owner`, `repo`, `tag_name`, `target`, `title`. Optional: `body`, `is_draft`, `is_pre_release` |
| `delete_release` | Delete a release | Required: `owner`, `repo`, `id` |
> No "edit release" or "upload asset" tool — fall back to `tea releases edit` / `tea releases assets` for those.
## Issues
| Tool | Purpose | Methods |
|------|---------|---------|
| `list_issues` | Standalone list | Filters: `state`, `labels[]`, `since`, `before` |
| `search_issues` | Cross-repo search | Required: `query`. Filters: `state`, `type` (issues/pulls), `labels`, `owner` |
| `issue_read` | Read details | `get`, `get_comments`, `get_labels` |
| `issue_write` | Mutate | `create`, `update`, `add_comment`, `edit_comment`, `add_labels`, `remove_label`, `replace_labels`, `clear_labels`. `labels` are IDs (numeric). `assignees` are usernames |
## Pull requests
| Tool | Purpose | Methods |
|------|---------|---------|
| `list_pull_requests` | List PRs | Filters: `state`, `milestone`, `sort` (`oldest`, `recentupdate`, `leastupdate`, `mostcomment`, `leastcomment`, `priority`) |
| `pull_request_read` | Read details | `get`, `get_diff`, `get_files`, `get_status` (head commit status), `get_reviews`, `get_review`, `get_review_comments` |
| `pull_request_write` | Mutate | `create`, `update`, `close`, `reopen`, `merge`, `update_branch`, `add_reviewers`, `remove_reviewers`. Merge styles: `merge`, `rebase`, `rebase-merge`, `squash`, `fast-forward-only`. Optional `head_commit_id` for conflict detection; `merge_when_checks_succeed`, `force_merge`, `delete_branch` for merge |
| `pull_request_review_write` | Reviews | `create`, `submit`, `delete`, `dismiss`. States for `create`: `APPROVED`, `REQUEST_CHANGES`, `COMMENT`, `PENDING`. Supports inline `comments[]` with `path` + `new_line_num`/`old_line_num` |
## Labels
| Tool | Purpose | Methods |
|------|---------|---------|
| `label_read` | Read | `list_repo_labels`, `get_repo_label`, `list_org_labels` |
| `label_write` | Mutate | `create_repo_label`, `edit_repo_label`, `delete_repo_label`, `create_org_label`, `edit_org_label`, `delete_org_label`. Org labels accept `exclusive`; repo labels accept `is_archived`. `color` is hex `#RRGGBB` |
## Milestones
| Tool | Purpose | Methods |
|------|---------|---------|
| `milestone_read` | Read | `list`, `get` |
| `milestone_write` | Mutate | `create`, `update` (alias `edit`), `delete`. State enum: `open`, `closed`. `due_on` is a date string |
## Wiki
| Tool | Purpose | Methods |
|------|---------|---------|
| `wiki_read` | Read | `list`, `get` (needs `pageName`), `get_revisions` (needs `pageName`) |
| `wiki_write` | Mutate | `create` (needs `title`, `content`), `update` (needs `pageName`, `content`), `delete` (needs `pageName`). Optional `message` is the commit message |
> See `../../gitea-wiki/SKILL.md` for end-to-end wiki examples.
## Actions
| Tool | Purpose | Methods |
|------|---------|---------|
| `actions_config_read` | Read secrets/variables | `list_repo_secrets`, `list_org_secrets`, `list_repo_variables`, `get_repo_variable`, `list_org_variables`, `get_org_variable` |
| `actions_config_write` | Mutate secrets/variables | `upsert_repo_secret`, `delete_repo_secret`, `upsert_org_secret`, `delete_org_secret`, `create_repo_variable`, `update_repo_variable`, `delete_repo_variable`, `create_org_variable`, `update_org_variable`, `delete_org_variable`. Secret `value` field is `data`; variable value is `value` |
| `actions_run_read` | Read workflows/runs/jobs/logs | `list_workflows`, `get_workflow` (`workflow_id` may be ID or filename), `list_runs`, `get_run`, `list_jobs`, `list_run_jobs`, `get_job_log_preview`, `download_job_log` (`output_path` required). Log methods accept `max_bytes` and `tail_lines` |
| `actions_run_write` | Trigger/control runs | `dispatch_workflow` (needs `workflow_id`, `ref`; optional `inputs`), `cancel_run`, `rerun_run` |
## Notifications
| Tool | Purpose | Methods |
|------|---------|---------|
| `notification_read` | Read | `list` (optional `owner`/`repo` to scope; filters: `status`, `subject_type`, `since`, `before`), `get` (by thread `id`) |
| `notification_write` | Mark read | `mark_read` (by thread `id`), `mark_all_read` (optionally scoped to a repo) |
## Packages
| Tool | Purpose | Methods |
|------|---------|---------|
| `package_read` | Read | `list` (one entry per version; filter via `q`/`type`), `list_versions`, `get` (needs `version`) |
| `package_write` | Mutate | `delete` (irreversible) |
Package `type`: `container`, `npm`, `maven`, `pypi`, `cargo`, `generic`.
## Time tracking
| Tool | Purpose | Methods |
|------|---------|---------|
| `timetracking_read` | Read | `list_issue_times`, `list_repo_times`, `get_my_stopwatches`, `get_my_times` |
| `timetracking_write` | Mutate | `start_stopwatch`, `stop_stopwatch`, `delete_stopwatch`, `add_time` (`time` in seconds), `delete_time` |
## Users / Orgs / Teams
| Tool | Purpose | Notes |
|------|---------|-------|
| `get_me` | Current user | No args |
| `get_user_orgs` | Orgs of the current user | Paginated |
| `search_users` | Search users | Required: `query` |
| `search_org_teams` | Search teams in an org | Required: `org`, `query`. Optional: `includeDescription` |
## Server
| Tool | Purpose |
|------|---------|
| `get_gitea_mcp_server_version` | Returns the running MCP server version. Useful for confirming connectivity. |
## Coverage gaps (use `tea` or REST API instead)
The MCP server does **not** currently expose:
- Webhook CRUD — use `tea webhooks …`.
- Admin user CRUD — use `tea admin users …`.
- Release asset upload/management — use `tea releases assets …`.
- SSH key CRUD — use `tea ssh-keys …`.
- Login / instance setup — `tea logins …`.
- Repo edit/delete — `tea repos edit / tea repos delete --owner X --name Y --force`.
- `tea pulls checkout` / `tea clone` workflows that need local git state.