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

github.com

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

git@gitea.com:

https://gitea.com/

owner/repo

--repo

tea CLI Reference (Fallback)

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

Pull Requests

tea pr create --title "Title" --description "Description"

tea pr list

tea pr list --state open

tea pr view <id>

tea pr checkout <id>

tea pr merge <id>

tea pr close <id>

tea pr reopen <id>

tea pr review <id> --approve

tea pr clean

Issues

tea issue create --title "Title" --body "Description"

tea issue list

tea issue list --state open

tea issue list --state closed

tea issue view <id>

tea issue close <id>

tea issue reopen <id>

tea issue comment <id> "Comment text"

tea issue edit <id> --title "New Title"

Repositories

tea repo clone <owner/repo>

tea repo fork <owner/repo>

tea repo create --name <name>

tea repo create-from-template <template-owner/repo> --name <name>

tea repos list

tea repos search <query>

Releases

tea release list

tea release create --tag <tag> --title "Title"

tea release delete <tag>

Labels

tea label list

tea label create --name "bug" --color "#ff0000"

tea label delete <name>

tea label export

Milestones

tea milestone list

tea milestone create --title "v1.0"

tea milestone close <name>

Organizations

tea org list

tea org view <name>

Notifications

tea notifications

tea notifications --mark-read

Time Tracking

tea times list

tea times add <issue-id> <duration>

tea times delete <id>

Authentication

tea login list

tea login add

tea login default <name>

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

-l, --login

-r, --repo

-o, --output

--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/