forked from farhoodlabs/skills
113 lines
6.2 KiB
Markdown
113 lines
6.2 KiB
Markdown
---
|
|
name: gitea
|
|
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 — repos, issues, PRs, releases, Actions CI/CD, packages, and wiki. This is a **parent skill** that routes work to:
|
|
|
|
- **`gitea-tea`** — terminal operations via the `tea` CLI
|
|
- **`gitea-wiki`** — wiki pages via the MCP server or REST API
|
|
|
|
## Interaction methods (in order of preference)
|
|
|
|
| Priority | Method | Coverage |
|
|
|----------|--------|----------|
|
|
| **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. |
|
|
|
|
**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`.
|
|
|
|
## Configuration
|
|
|
|
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 reach for `gh` or github.com, stop and re-route:
|
|
|
|
```
|
|
This repository uses Gitea for source code management, not GitHub.
|
|
Use the `gitea` MCP server first, or `tea` CLI as fallback.
|
|
Do NOT use `gh` or GitHub-specific features.
|
|
```
|
|
|
|
## 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 `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
|
|
Wiki page CRUD via the MCP server (`wiki_read`/`wiki_write`) or REST API. `tea` has no wiki subcommands. See `../gitea-wiki/SKILL.md`.
|
|
|
|
## 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
|
|
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>
|
|
- 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>
|