194 lines
4.4 KiB
Markdown
194 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cd gitea-shim/python
|
|
pip install -e .
|
|
```
|
|
|
|
### JavaScript/TypeScript
|
|
|
|
```bash
|
|
cd gitea-shim/javascript
|
|
npm install
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Python (PyGitHub Compatible)
|
|
|
|
Instead of using PyGitHub:
|
|
|
|
```python
|
|
# Old GitHub code
|
|
from github import Github
|
|
gh = Github(token)
|
|
repo = gh.get_repo("owner/repo")
|
|
```
|
|
|
|
Use the Gitea shim:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```javascript
|
|
// 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:
|
|
|
|
```javascript
|
|
// 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
|
|
|
|
```bash
|
|
# Python
|
|
pip install gitea-github-shim
|
|
|
|
# JavaScript
|
|
npm install gitea-github-shim
|
|
```
|
|
|
|
### Step 2: Update imports
|
|
|
|
Python:
|
|
```python
|
|
# Replace
|
|
from github import Github
|
|
|
|
# With
|
|
from gitea_github_shim import GiteaGitHubShim as Github
|
|
```
|
|
|
|
JavaScript:
|
|
```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:
|
|
```python
|
|
gh = Github(token, base_url="https://your-gitea-instance.com")
|
|
```
|
|
|
|
JavaScript:
|
|
```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
|
|
|
|
```bash
|
|
# 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 |