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 (git@gitea.com:...) 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 (git@gitea.com: 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

Issues

Repositories

Releases

Labels

Milestones

Organizations

Notifications

Time Tracking

Authentication

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

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/