Yiqun/gitea-shim/README.md

Gitea GitHub SDK Shim

A compatibility layer that provides GitHub SDK interfaces (PyGitHub and Octokit) for Gitea repositories. This allows you to use existing GitHub-based code with Gitea instances with minimal changes.

Installation

Python

cd gitea-shim/python
pip install -e .

JavaScript/TypeScript

cd gitea-shim/javascript
npm install

Usage

Python (PyGitHub Compatible)

Instead of using PyGitHub:

# Old GitHub code
from github import Github
gh = Github(token)
repo = gh.get_repo("owner/repo")

Use the Gitea shim:

# New Gitea code
from gitea_github_shim import GiteaGitHubShim
gh = GiteaGitHubShim(token, base_url="https://your-gitea-instance.com")
repo = gh.get_repo("owner/repo")

Or with environment variables:

import os
os.environ['GITEA_URL'] = 'https://your-gitea-instance.com'

# Now you can use it just like GitHub
gh = GiteaGitHubShim(token)  # URL is taken from env
repo = gh.get_repo("owner/repo")

JavaScript/TypeScript (Octokit Compatible)

Instead of using Octokit:

// Old GitHub code
const { Octokit } = require("@octokit/rest");
const octokit = new Octokit({ auth: token });
const repo = await octokit.rest.repos.get({ owner, repo });

Use the Gitea shim:

// New Gitea code
const { GiteaOctokitShim } = require("gitea-shim");
const octokit = new GiteaOctokitShim({ 
  auth: token,
  baseUrl: "https://your-gitea-instance.com"
});
const repo = await octokit.rest.repos.get({ owner, repo });

Supported APIs

Repository Operations

• get_repo() / rest.repos.get() - Get repository
• create_repo() / rest.repos.createForAuthenticatedUser() - Create repository
• repo.default_branch - Get default branch
• repo.create_fork() / rest.repos.createFork() - Fork repository

Pull Request Operations

• repo.get_pull() / rest.pulls.get() - Get pull request
• repo.get_pulls() / rest.pulls.list() - List pull requests
• repo.create_pull() / rest.pulls.create() - Create pull request
• pr.update() / rest.pulls.update() - Update pull request
• pr.merge() / rest.pulls.merge() - Merge pull request

User Operations

• get_user() / rest.users.getAuthenticated() - Get user
• user.get_repos() - Get user repositories
• user.add_to_following() / rest.users.follow() - Follow user

Activity Operations

• user.get_starred() / rest.activity.listReposStarredByUser() - Get starred repos
• user.get_subscriptions() / rest.activity.listWatchedReposForUser() - Get watched repos

Environment Variables

• GITEA_URL - Base URL of your Gitea instance (e.g., https://gitea.example.com)
• GITEA_TOKEN - Personal access token for Gitea (you can still use GITHUB_TOKEN for compatibility)

Migration Guide

Step 1: Install the shim

# Python
pip install gitea-github-shim

# JavaScript
npm install gitea-github-shim

Step 2: Update imports

Python:

# Replace
from github import Github

# With
from gitea_github_shim import GiteaGitHubShim as Github

JavaScript:

// Replace
const { Octokit } = require("@octokit/rest");

// With
const { GiteaOctokitShim: Octokit } = require("gitea-github-shim");

Step 3: Update initialization

Add the Gitea URL when creating the client:

Python:

gh = Github(token, base_url="https://your-gitea-instance.com")

JavaScript:

const octokit = new Octokit({ 
  auth: token,
  baseUrl: "https://your-gitea-instance.com"
});

Step 4: Handle API differences

Some features may not be available or work differently in Gitea:

1. Draft PRs - May not be supported
2. Rate Limiting - Gitea typically doesn't have rate limits
3. GraphQL API - Not available in Gitea
4. Advanced Search - Limited compared to GitHub

Development

Running Tests

# Python tests
cd gitea-shim/python
python -m pytest tests/

# JavaScript tests
cd gitea-shim/javascript
npm test

Contributing

1. Check the todo.md file for pending tasks
2. Add tests for any new functionality
3. Update this README with new supported APIs
4. Submit a pull request

Limitations

• Some GitHub-specific features are not available in Gitea
• API responses may have slight differences in structure
• Not all endpoints are implemented yet
• GraphQL is not supported (REST API only)

License

MIT License - See LICENSE file for details