Add gitea-shim integration and update workflow services
This commit is contained in:
178
gitea-shim/python/README.md
Normal file
178
gitea-shim/python/README.md
Normal file
@ -0,0 +1,178 @@
|
||||
# Gitea GitHub Shim
|
||||
|
||||
A Python library that provides a GitHub-compatible interface for Gitea, allowing you to use the same code with both GitHub and Gitea APIs.
|
||||
|
||||
## Features
|
||||
|
||||
- **Drop-in replacement** for PyGitHub's `Github` class
|
||||
- **Automatic switching** between GitHub and Gitea based on environment variables
|
||||
- **GitHub-compatible interface** - minimal code changes required
|
||||
- **Error handling** and fallback mechanisms
|
||||
- **Comprehensive model wrappers** for repositories, users, and pull requests
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone this repository or copy the `gitea-shim/python` directory to your project
|
||||
2. Install the required dependencies:
|
||||
|
||||
```bash
|
||||
pip install gitea
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The shim automatically detects whether to use GitHub or Gitea based on environment variables:
|
||||
|
||||
### GitHub Mode (Default)
|
||||
```bash
|
||||
export GITHUB_TOKEN="your_github_token"
|
||||
# USE_GITEA is not set or set to 'false'
|
||||
```
|
||||
|
||||
### Gitea Mode
|
||||
```bash
|
||||
export USE_GITEA="true"
|
||||
export GITEA_URL="http://your-gitea-instance:3000"
|
||||
export GITEA_TOKEN="your_gitea_token" # or use GITHUB_TOKEN
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
from gitea_shim import get_github_client
|
||||
|
||||
# This will automatically use GitHub or Gitea based on your environment
|
||||
gh = get_github_client()
|
||||
|
||||
# Get a repository (works the same for both APIs)
|
||||
repo = gh.get_repo("owner/repo")
|
||||
|
||||
# Get user information
|
||||
user = gh.get_user()
|
||||
|
||||
# Create a pull request
|
||||
pr = repo.create_pull(
|
||||
title="My PR",
|
||||
body="Description",
|
||||
head="feature-branch",
|
||||
base="main"
|
||||
)
|
||||
```
|
||||
|
||||
### Migration from PyGitHub
|
||||
|
||||
**Before (PyGitHub only):**
|
||||
```python
|
||||
from github import Github
|
||||
|
||||
gh = Github("your_token")
|
||||
repo = gh.get_repo("owner/repo")
|
||||
```
|
||||
|
||||
**After (with shim):**
|
||||
```python
|
||||
from gitea_shim import get_github_client
|
||||
|
||||
gh = get_github_client() # Works with both GitHub and Gitea
|
||||
repo = gh.get_repo("owner/repo") # Same interface!
|
||||
```
|
||||
|
||||
### Advanced Configuration
|
||||
|
||||
```python
|
||||
from gitea_shim import config, is_gitea_mode, get_api_info
|
||||
|
||||
# Check which API you're using
|
||||
if is_gitea_mode():
|
||||
print("Using Gitea API")
|
||||
else:
|
||||
print("Using GitHub API")
|
||||
|
||||
# Get detailed API information
|
||||
api_info = get_api_info()
|
||||
print(f"API Type: {api_info['type']}")
|
||||
print(f"URL: {api_info['url']}")
|
||||
print(f"Token Set: {api_info['token_set']}")
|
||||
```
|
||||
|
||||
## Supported Methods
|
||||
|
||||
### Client Methods
|
||||
- `get_repo(full_name)` - Get repository by owner/repo name
|
||||
- `get_user(login=None)` - Get user (authenticated or by login)
|
||||
- `get_organization(login)` - Get organization
|
||||
- `create_repo(name, **kwargs)` - Create new repository
|
||||
- `search_repositories(query, **kwargs)` - Search repositories
|
||||
- `search_users(query, **kwargs)` - Search users
|
||||
- `get_api_status()` - Get API status
|
||||
- `get_rate_limit()` - Get rate limit info
|
||||
- `get_emojis()` - Get available emojis
|
||||
- `get_gitignore_templates()` - Get gitignore templates
|
||||
- `get_license_templates()` - Get license templates
|
||||
|
||||
### Repository Methods
|
||||
- `get_pull(number)` - Get pull request by number
|
||||
- `get_pulls(**kwargs)` - Get list of pull requests
|
||||
- `create_pull(title, body, head, base, **kwargs)` - Create pull request
|
||||
- `get_contents(path, ref=None)` - Get file contents
|
||||
- `get_branches()` - Get all branches
|
||||
- `get_branch(branch)` - Get specific branch
|
||||
- `create_fork(organization=None)` - Fork repository
|
||||
- `get_commits(**kwargs)` - Get commits
|
||||
- `get_commit(sha)` - Get specific commit
|
||||
|
||||
### Pull Request Methods
|
||||
- `update(**kwargs)` - Update pull request
|
||||
- `merge(**kwargs)` - Merge pull request
|
||||
- `get_commits()` - Get commits in PR
|
||||
- `get_files()` - Get files changed in PR
|
||||
- `create_review_comment(body, commit_id, path, position)` - Add review comment
|
||||
- `create_issue_comment(body)` - Add issue comment
|
||||
|
||||
## Testing
|
||||
|
||||
Run the test suite to verify the shim works correctly:
|
||||
|
||||
```bash
|
||||
cd gitea-shim/python
|
||||
python test_shim.py
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `USE_GITEA` | Enable Gitea mode | `false` |
|
||||
| `GITEA_URL` | Gitea instance URL | `http://localhost:3000` |
|
||||
| `GITHUB_TOKEN` | GitHub/Gitea API token | Required |
|
||||
| `GITEA_TOKEN` | Gitea-specific token (optional) | Uses `GITHUB_TOKEN` |
|
||||
|
||||
## Error Handling
|
||||
|
||||
The shim includes comprehensive error handling:
|
||||
|
||||
- **Graceful fallbacks** when Gitea methods don't exist
|
||||
- **Compatible error messages** with GitHub's error format
|
||||
- **Automatic retry logic** for transient failures
|
||||
- **Detailed logging** for debugging
|
||||
|
||||
## Limitations
|
||||
|
||||
- Some GitHub-specific features may not be available in Gitea
|
||||
- Rate limiting is mocked for Gitea (returns unlimited)
|
||||
- Some advanced search features may differ between APIs
|
||||
- Draft pull requests may not be supported in all Gitea versions
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Add tests for new functionality
|
||||
4. Ensure all tests pass
|
||||
5. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
Reference in New Issue
Block a user