mcphub/docs/GITEA_GUIDE.md

🦊 Gitea Plugin Guide

Complete guide for Gitea integration in MCP Hub

Version: 1.0.0 (Phase C) Last Updated: 2025-11-19

---

📋 Table of Contents

• Overview
• Features
• Installation
• Configuration
• Tool Categories
• Usage Examples
• OAuth Integration
• API Reference
• Troubleshooting
• Best Practices

---

🎯 Overview

The Gitea Plugin provides comprehensive Git repository management through Gitea's REST API. It enables AI assistants (like Claude) to manage repositories, issues, pull requests, and more directly from ChatGPT or other MCP-enabled clients.

What is Gitea?

Gitea is a lightweight, self-hosted Git service similar to GitHub/GitLab. It provides:

• Git repository hosting
• Issue tracking
• Pull requests
• Code review
• Webhooks
• Organizations and teams

Why This Plugin?

✅ Git Workflow Automation - Manage repositories from ChatGPT ✅ CI/CD Integration - Trigger deployments with PR merges ✅ Issue Management - AI-assisted issue triaging and responses ✅ Code Review - Automated PR reviews and suggestions ✅ OAuth Support - Seamless ChatGPT integration ✅ Multi-Site - Manage multiple Gitea instances

---

✨ Features

📦 Repository Management (15 Tools)

• CRUD Operations: Create, read, update, delete repositories
• Branch Management: List, create, delete branches
• Tag Management: Create and manage tags
• File Operations: Read, create, update files in repository

🐛 Issue Tracking (12 Tools)

• Issue Management: Create, update, close, reopen issues
• Labels: Create and manage issue labels
• Milestones: Track project milestones
• Comments: Add comments to issues

🔀 Pull Requests (15 Tools)

• PR Operations: Create, update, merge pull requests
• Code Review: Review PRs, request changes, approve
• PR Details: View commits, files, diff
• Reviewers: Request reviewers for PRs

👥 User & Organization (8 Tools)

• User Management: Get user info, list repositories
• Organizations: Manage organizations and teams
• Teams: List team members
• Search: Search for users

🔗 Webhooks (5 Tools)

• Webhook Setup: Create, list, delete webhooks
• Event Configuration: Configure webhook events
• Testing: Test webhook delivery

Total: 55 Tools

---

📦 Installation

Prerequisites

• Gitea instance (self-hosted or managed)
• Gitea personal access token OR OAuth setup
• MCP Hub installed

1. Enable Gitea Plugin

The Gitea plugin is built-in. No additional installation needed.

2. Configure Environment

Edit .env file:

# Site 1 - Token Authentication
GITEA_SITE1_URL=https://gitea.mcphub.dev
GITEA_SITE1_TOKEN=your_personal_access_token_here
GITEA_SITE1_ALIAS=mygitea

# Site 2 - OAuth Authentication (for ChatGPT)
GITEA_SITE2_URL=https://git.company.com
GITEA_SITE2_OAUTH_ENABLED=true
GITEA_SITE2_ALIAS=workgit

3. Generate Personal Access Token

In Gitea:

1. Log in to your Gitea instance
2. Go to Settings → Applications
3. Click Generate New Token
4. Enter token name: MCP Server
5. Select permissions:
   • ✅ repo (all) - Full repository access
   • ✅ write:org - Manage organizations
   • ✅ read:user - Read user information
   • ✅ write:issue - Create/edit issues and PRs
6. Click Generate Token
7. Copy the token (shown only once!)
8. Add to .env as GITEA_SITE1_TOKEN

4. Restart Server

# If running locally
python server.py

# If running in Docker
docker-compose restart

# If deployed in Coolify
# Restart the service from Coolify dashboard

5. Verify Installation

Check server logs for:

✅ Gitea plugin loaded: gitea_site1 (mygitea)

Or use health check tool:

check_project_health(project_id="gitea_site1")

---

⚙️ Configuration

Environment Variables

Variable	Required	Default	Description
GITEA_SITEX_URL	✅ Yes	-	Gitea instance URL
GITEA_SITEX_TOKEN	⚠️ Conditional	-	Personal access token (required if not using OAuth)
GITEA_SITEX_ALIAS	❌ No	-	Friendly site name
GITEA_SITEX_OAUTH_ENABLED	❌ No	false	Enable OAuth instead of token

Multiple Sites

You can configure unlimited Gitea instances:

# Personal Gitea
GITEA_SITE1_URL=https://gitea.mcphub.dev
GITEA_SITE1_TOKEN=token1
GITEA_SITE1_ALIAS=personal

# Work Gitea
GITEA_SITE2_URL=https://git.company.com
GITEA_SITE2_TOKEN=token2
GITEA_SITE2_ALIAS=work

# Client Gitea
GITEA_SITE3_URL=https://git.client.com
GITEA_SITE3_TOKEN=token3
GITEA_SITE3_ALIAS=client

OAuth vs Token Authentication

Token Authentication (Recommended for Scripts)

✅ Pros:

• Simple setup
• No user interaction needed
• Suitable for automation

❌ Cons:

• Tokens can expire
• Manual renewal needed
• Less secure if leaked

OAuth Authentication (Recommended for ChatGPT)

✅ Pros:

• User-approved access
• More secure
• Automatic token refresh
• Better for third-party apps

❌ Cons:

• Requires OAuth setup
• More complex configuration

---

🧰 Tool Categories

1. Repository Tools

List Repositories

gitea_list_repositories(site, owner?, type?, page?, limit?)

Example:

# List all my repositories
gitea_list_repositories(site="mygitea")

# List user's repositories
gitea_list_repositories(site="mygitea", owner="username")

Create Repository

gitea_create_repository(site, name, description?, private?, auto_init?)

Example:

gitea_create_repository(
    site="mygitea",
    name="awesome-project",
    description="My awesome project",
    private=False,
    auto_init=True
)

Manage Branches

gitea_list_branches(site, owner, repo)
gitea_create_branch(site, owner, repo, new_branch_name, old_branch_name?)
gitea_delete_branch(site, owner, repo, branch)

File Operations

gitea_get_file(site, owner, repo, path, ref?)
gitea_create_file(site, owner, repo, path, content, message)
gitea_update_file(site, owner, repo, path, content, sha, message)

2. Issue Tools

Manage Issues

gitea_list_issues(site, owner, repo, state?, labels?, q?)
gitea_create_issue(site, owner, repo, title, body?, labels?)
gitea_update_issue(site, owner, repo, issue_number, ...)
gitea_close_issue(site, owner, repo, issue_number)

Labels & Milestones

gitea_list_labels(site, owner, repo)
gitea_create_label(site, owner, repo, name, color, description?)
gitea_list_milestones(site, owner, repo, state?)
gitea_create_milestone(site, owner, repo, title, due_on?)

3. Pull Request Tools

Manage PRs

gitea_create_pull_request(site, owner, repo, title, head, base, body?)
gitea_merge_pull_request(site, owner, repo, pr_number, method?)
gitea_list_pr_commits(site, owner, repo, pr_number)
gitea_list_pr_files(site, owner, repo, pr_number)

Code Review

gitea_create_pr_review(site, owner, repo, pr_number, event, body?)
gitea_request_pr_reviewers(site, owner, repo, pr_number, reviewers)

4. User & Organization Tools

gitea_get_user(site, username)
gitea_list_user_repos(site, username)
gitea_list_organizations(site)
gitea_list_org_teams(site, org)

5. Webhook Tools

gitea_list_webhooks(site, owner, repo)
gitea_create_webhook(site, owner, repo, url, events)
gitea_test_webhook(site, owner, repo, webhook_id)

---

💡 Usage Examples

Example 1: Create a Repository

# Create a new repository with README
gitea_create_repository(
    site="mygitea",
    name="my-new-project",
    description="A new project for testing",
    private=False,
    auto_init=True,
    license="MIT"
)

Example 2: Create an Issue

# Create an issue
gitea_create_issue(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    title="Bug: Login not working",
    body="## Description\n\nUsers cannot log in after the latest update.\n\n## Steps to Reproduce\n1. Go to login page\n2. Enter credentials\n3. Click login\n\n## Expected\nShould log in successfully\n\n## Actual\nError message displayed",
    labels=[1, 3]  # bug, high-priority
)

Example 3: Create a Pull Request

# Create feature branch
gitea_create_branch(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    new_branch_name="feature/user-authentication",
    old_branch_name="main"
)

# Make changes to files
gitea_update_file(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    path="src/auth.js",
    content="// Updated authentication code\n...",
    sha="abc123",
    message="Add OAuth support",
    branch="feature/user-authentication"
)

# Create pull request
gitea_create_pull_request(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    title="Add OAuth Authentication",
    head="feature/user-authentication",
    base="main",
    body="This PR adds OAuth support for Google and GitHub authentication."
)

Example 4: Review and Merge PR

# List open PRs
gitea_list_pull_requests(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    state="open"
)

# Review the PR
gitea_create_pr_review(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    pr_number=5,
    event="APPROVED",
    body="LGTM! Great work on the OAuth implementation."
)

# Merge the PR
gitea_merge_pull_request(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    pr_number=5,
    method="squash",
    delete_branch_after_merge=True
)

Example 5: Setup Webhook for CI/CD

# Create webhook for Coolify deployment
gitea_create_webhook(
    site="mygitea",
    owner="myuser",
    repo="my-project",
    url="https://coolify.example.com/webhooks/deploy",
    events=["push", "pull_request"],
    content_type="json",
    secret="webhook_secret_here"
)

---

🔐 OAuth Integration

Setup OAuth for ChatGPT

1. Configure Server

In .env:

# Enable OAuth for Gitea site
GITEA_SITE1_URL=https://gitea.mcphub.dev
GITEA_SITE1_OAUTH_ENABLED=true
GITEA_SITE1_ALIAS=mygitea

# OAuth settings (if not already set)
OAUTH_JWT_SECRET_KEY=your_jwt_secret_here
OAUTH_AUTH_MODE=trusted_domains
OAUTH_TRUSTED_DOMAINS=chatgpt.com,chat.openai.com,openai.com

2. Create GPT Action

In ChatGPT GPTs:

1. Go to Configure → Actions
2. Click Create new action
3. Import OpenAPI schema from: https://your-server.com/.well-known/oauth-authorization-server
4. Set OAuth:
   • Client ID: Auto-registered via dynamic registration
   • Authorization URL: https://your-server.com/oauth/authorize
   • Token URL: https://your-server.com/oauth/token

3. Use from ChatGPT

User: "Create a new repository called 'test-repo' in my Gitea"

Claude: Sure! I'll create a new repository.
[Calls gitea_create_repository with OAuth token]

API Key with OAuth

For additional security, you can require API Keys even with OAuth:

OAUTH_AUTH_MODE=required

Then users must provide API Key in authorization URL:

/oauth/authorize?client_id=xxx&...&api_key=cmp_your_key_here

---

📚 API Reference

Tool Naming Convention

All Gitea tools follow this pattern:

gitea_<action>_<resource>(site, ...params)

Examples:

• gitea_create_repository
• gitea_list_issues
• gitea_merge_pull_request

Common Parameters

Parameter	Type	Required	Description
site	string	✅	Site ID or alias (e.g., "mygitea")
owner	string	✅	Repository owner username/org
repo	string	✅	Repository name
page	integer	❌	Page number (default: 1)
limit	integer	❌	Items per page (default: 30, max: 100)

Response Format

All tools return consistent response format:

Success:

{
  "success": true,
  "message": "Operation completed",
  "data": { ... }
}

Error:

{
  "error": true,
  "message": "Error description",
  "code": "ERROR_CODE"
}

---

🔧 Troubleshooting

Common Issues

1. "Authentication failed"

Cause: Invalid or expired token

Solution:

• Regenerate personal access token in Gitea
• Update GITEA_SITEX_TOKEN in .env
• Restart server

2. "Repository not found"

Cause: Incorrect owner or repo name

Solution:

• Verify repository exists in Gitea
• Check spelling of owner/repo
• Ensure user has access to repository

3. "Permission denied"

Cause: Token lacks required permissions

Solution:

• Regenerate token with correct permissions:
  • repo (all)
  • write:org
  • read:user
  • write:issue

4. "Webhook creation failed"

Cause: Invalid webhook URL or insufficient permissions

Solution:

• Verify webhook URL is accessible
• Ensure user has admin access to repository
• Check webhook events are valid

Debug Mode

Enable debug logging:

LOG_LEVEL=DEBUG

Check logs:

tail -f logs/audit.log | jq

Health Check

Test Gitea connectivity:

check_project_health(project_id="gitea_site1")

Expected response:

{
  "healthy": true,
  "message": "Gitea instance is accessible"
}

---

✅ Best Practices

1. Security

• ✅ Use personal access tokens with minimal required permissions
• ✅ Enable OAuth for third-party access (ChatGPT)
• ✅ Rotate tokens regularly
• ✅ Use private repositories for sensitive code
• ✅ Enable webhook secrets for webhook security
• ✅ Use per-project API keys instead of master key

2. Git Workflow

• ✅ Create feature branches for new features
• ✅ Use pull requests for code review
• ✅ Add meaningful commit messages
• ✅ Use labels for issue categorization
• ✅ Set milestones for project planning
• ✅ Squash merge to keep history clean

3. Automation

• ✅ Setup webhooks for CI/CD integration
• ✅ Auto-close issues when PR is merged
• ✅ Use labels to trigger automation
• ✅ Create templates for issues and PRs

4. Performance

• ✅ Use pagination for large result sets
• ✅ Cache repository information when possible
• ✅ Use search instead of listing all items
• ✅ Batch operations when possible

---

🎯 Use Cases

1. Automated Issue Triage

# AI assistant automatically:
1. Lists open issues
2. Analyzes issue content
3. Adds appropriate labels
4. Assigns to team members
5. Sets milestone

2. AI Code Review

# AI assistant reviews PRs:
1. Lists open PRs
2. Gets PR diff
3. Analyzes code changes
4. Adds review comments
5. Approves or requests changes

3. Automated Releases

# Create release workflow:
1. Create release branch
2. Update version numbers
3. Generate changelog
4. Create pull request
5. After merge: create tag and release

4. Documentation Updates

# Keep docs in sync:
1. Detect code changes
2. Update corresponding documentation
3. Create PR for doc updates
4. Request review from maintainers

---

📖 Related Documentation

• OAuth Guide - Complete OAuth 2.1 setup
• API Keys Guide - API key management
• Gitea API Docs - Official Gitea API

---

🆘 Support

Need Help?

• 📧 Email: hello@mcphub.dev
• 🐛 Issues: GitHub Issues
• 📚 Docs: Full Documentation

Contributing

Contributions welcome! See CONTRIBUTING.md

---

Version: 3.0.0