jason-hchsieh/gitea

Gitea Skill

This plugin provides two ways to interact with Gitea:

1. gitea-mcp (preferred) - MCP server providing 80+ tools for direct API integration
2. tea CLI (fallback) - Command-line interface for Gitea operations

When to Use This Skill

Activate this skill when:

• User mentions "gitea", "tea", or Gitea-related operations
• Working with repositories hosted on Gitea instances (not GitHub/GitLab)
• Managing issues, pull requests, releases, or repos
• Automating Gitea workflows

Detection: Run git remote -v to check if the remote URL points to a Gitea instance (doesn't contain github.com or gitlab).

Tool Selection Priority

1. Try gitea-mcp First (Preferred)

The MCP server provides 80+ tools for:

• Repository management (create, fork, list, search)
• Issues and PRs (CRUD, comments, reviews)
• Branches, tags, and releases
• File operations (read/write)
• Actions (workflows, secrets, runs)
• Organizations and teams
• Wiki pages

Requirements:

• GITEA_ACCESS_TOKEN environment variable set
• gitea-mcp binary installed and in PATH

2. Fall Back to tea CLI When:

• GITEA_ACCESS_TOKEN is not set
• gitea-mcp tools return authentication errors
• MCP server is not available
• User explicitly requests tea CLI

3. If Both Fail, Offer to Install

If both gitea-mcp and tea CLI are unavailable or fail:

1. Inform the user about the issue
2. Ask if they want help installing the requirements
3. Refer to the plugin README for installation instructions

Authentication

For gitea-mcp (environment variable)

export GITEA_ACCESS_TOKEN=your_token
export GITEA_HOST=https://your-gitea-instance.com  # optional, default: https://gitea.com

For tea CLI (interactive login)

# Check existing logins
tea login list

# Add new login (interactive)
tea login add

Generate tokens: Gitea web UI → Settings → Applications → Generate New Token

Behavioral Guidelines

1. Try MCP First: Attempt gitea-mcp tools before falling back to tea CLI
2. Before PR Creation: Check for uncommitted changes with git status
3. Before CI Operations: Verify pipeline status before triggering new runs
4. Machine-Readable Output: When using tea CLI, use -o json or -o yaml flags for automation
5. Custom SSH Remotes: Always use --repo owner/repo flag when remote URL is non-standard (see below)

Handling Custom SSH Remotes

Problem: tea CLI auto-detects the repository from git remote URLs, but fails with custom SSH aliases like:

• ngit@gitea:owner/repo.git
• git@custom-host:owner/repo.git
• Any non-standard SSH URL format

Error: Error: path segment [0] is empty

Solution: Always specify the repo explicitly with --repo owner/repo:

# Check remote URL format first
git remote -v

# If remote uses custom SSH alias (e.g., ngit@gitea:...), always use --repo
tea pr create --repo owner/repo --title "Title" --description "Description"
tea issue list --repo owner/repo
tea pr list --repo owner/repo

# Standard URLs ([email protected]:...) work without --repo
tea pr create --title "Title" --description "Description"

Detection: Run git remote -v at the start. If the URL doesn't match standard patterns ([email protected]: or https://gitea.com/), extract owner/repo from the path and use --repo for all tea commands.

---

tea CLI Reference (Fallback)

Use these commands when gitea-mcp is unavailable or returns errors.

Pull Requests

| Operation | Command | |-----------|---------| | Create PR | tea pr create --title "Title" --description "Description" | | List PRs | tea pr list | | List open PRs | tea pr list --state open | | View PR | tea pr view <id> | | Checkout PR | tea pr checkout <id> | | Merge PR | tea pr merge <id> | | Close PR | tea pr close <id> | | Reopen PR | tea pr reopen <id> | | Review PR | tea pr review <id> --approve | | Clean merged branches | tea pr clean |

Issues

| Operation | Command | |-----------|---------| | Create issue | tea issue create --title "Title" --body "Description" | | List issues | tea issue list | | List open issues | tea issue list --state open | | List closed issues | tea issue list --state closed | | View issue | tea issue view <id> | | Close issue | tea issue close <id> | | Reopen issue | tea issue reopen <id> | | Add comment | tea issue comment <id> "Comment text" | | Edit issue | tea issue edit <id> --title "New Title" |

Repositories

| Operation | Command | |-----------|---------| | Clone repo | tea repo clone <owner/repo> | | Fork repo | tea repo fork <owner/repo> | | Create repo | tea repo create --name <name> | | Create from template | tea repo create-from-template <template-owner/repo> --name <name> | | List repos | tea repos list | | Search repos | tea repos search <query> |

Releases

| Operation | Command | |-----------|---------| | List releases | tea release list | | Create release | tea release create --tag <tag> --title "Title" | | Delete release | tea release delete <tag> |

Labels

| Operation | Command | |-----------|---------| | List labels | tea label list | | Create label | tea label create --name "bug" --color "#ff0000" | | Delete label | tea label delete <name> | | Export labels | tea label export |

Milestones

| Operation | Command | |-----------|---------| | List milestones | tea milestone list | | Create milestone | tea milestone create --title "v1.0" | | Close milestone | tea milestone close <name> |

Organizations

| Operation | Command | |-----------|---------| | List orgs | tea org list | | View org | tea org view <name> |

Notifications

| Operation | Command | |-----------|---------| | List notifications | tea notifications | | Mark as read | tea notifications --mark-read |

Time Tracking

| Operation | Command | |-----------|---------| | List time entries | tea times list | | Add time | tea times add <issue-id> <duration> | | Delete time | tea times delete <id> |

Authentication

| Operation | Command | |-----------|---------| | List logins | tea login list | | Add login | tea login add | | Set default | tea login default <name> | | Delete login | tea login delete <name> |

Output Formats

Tea supports multiple output formats for automation:

# JSON output
tea issue list -o json
tea pr list -o json

# YAML output
tea issue list -o yaml

# Simple/minimal output
tea issue list -o simple

Common Workflows

Create a Pull Request

# Check for uncommitted changes first
git status

# Check remote URL format
git remote -v

# If using custom SSH remote (e.g., ngit@gitea:...), use --repo explicitly
tea pr create --repo owner/repo --title "Add new feature" --description "This PR adds..."

# For standard remotes, --repo is optional
tea pr create --title "Add new feature" --description "This PR adds..."

# Or interactively
tea pr create

Work on an Issue

# View the issue
tea issue view 42

# Checkout related PR if exists
tea pr checkout 42

# Add a comment
tea issue comment 42 "Working on this now"

# Close when done
tea issue close 42

Quick Repository Setup

# Clone a repository
tea repo clone owner/repo

# Or fork first then clone
tea repo fork owner/repo
tea repo clone your-username/repo

CI/Actions Secrets

# List secrets
tea repo secrets list

# Add a secret
tea repo secrets add <name> <value>

# Delete a secret
tea repo secrets delete <name>

Global Flags

| Flag | Description | |------|-------------| | -l, --login | Use a specific login | | -r, --repo | Override repository | | -o, --output | Output format (simple, table, csv, tsv, yaml, json) | | --remote | Use specific git remote |

Installation

# macOS
brew install tea

# Arch Linux
pacman -S tea

# Alpine
apk add tea

# From binary
# Download from https://dl.gitea.com/tea/

# Docker
docker pull gitea/tea

Resources

• Official Repository: https://gitea.com/gitea/tea
• Documentation: https://docs.gitea.com/usage/command-line
• Downloads: https://dl.gitea.com/tea/