Yiqun/gitea-shim/python/MIGRATION.md

# Migration Guide for Workflows

This guide shows how to migrate your workflow files from direct GitHub API usage to the Gitea shim.

## Quick Migration

### Step 1: Add Import Path

Add this to the top of your workflow files:

```python
import sys
from pathlib import Path

# Add the gitea-shim to the path
gitea_shim_path = Path(__file__).parent.parent.parent.parent.parent / "gitea-shim" / "python"
sys.path.insert(0, str(gitea_shim_path))

try:
    from gitea_shim import get_github_client, is_gitea_mode
except ImportError:
    # Fallback to regular GitHub if shim is not available
    from github import Github as get_github_client
    is_gitea_mode = lambda: False
```

### Step 2: Replace GitHub Client Creation

**Before:**
```python
from github import Github
gh = Github(os.getenv("GITHUB_TOKEN"))
```

**After:**
```python
gh = get_github_client()
```

### Step 3: Add Logging (Optional)

Add logging to see which API you're using:

```python
log_key_value("API Mode", "Gitea" if is_gitea_mode() else "GitHub")
```

## Complete Example

### Before Migration

```python
"""Task decomposition workflow implementation."""

import os
from github import Github
import requests
from prometheus_swarm.workflows.base import Workflow
# ... other imports

class RepoSummarizerWorkflow(Workflow):
    def setup(self):
        """Set up repository and workspace."""
        check_required_env_vars(["GITHUB_TOKEN", "GITHUB_USERNAME"])
        validate_github_auth(os.getenv("GITHUB_TOKEN"), os.getenv("GITHUB_USERNAME"))

        # Get the default branch from GitHub
        try:
            gh = Github(os.getenv("GITHUB_TOKEN"))
            self.context["repo_full_name"] = (
                f"{self.context['repo_owner']}/{self.context['repo_name']}"
            )

            repo = gh.get_repo(
                f"{self.context['repo_owner']}/{self.context['repo_name']}"
            )
            self.context["base"] = repo.default_branch
            log_key_value("Default branch", self.context["base"])
        except Exception as e:
            log_error(e, "Failed to get default branch, using 'main'")
            self.context["base"] = "main"
```

### After Migration

```python
"""Task decomposition workflow implementation."""

import os
import sys
from pathlib import Path

# Add the gitea-shim to the path
gitea_shim_path = Path(__file__).parent.parent.parent.parent.parent / "gitea-shim" / "python"
sys.path.insert(0, str(gitea_shim_path))

try:
    from gitea_shim import get_github_client, is_gitea_mode
except ImportError:
    # Fallback to regular GitHub if shim is not available
    from github import Github as get_github_client
    is_gitea_mode = lambda: False

import requests
from prometheus_swarm.workflows.base import Workflow
# ... other imports

class RepoSummarizerWorkflow(Workflow):
    def setup(self):
        """Set up repository and workspace."""
        check_required_env_vars(["GITHUB_TOKEN", "GITHUB_USERNAME"])
        validate_github_auth(os.getenv("GITHUB_TOKEN"), os.getenv("GITHUB_USERNAME"))

        # Get the default branch from GitHub/Gitea
        try:
            # Use the shim to get GitHub-compatible client
            gh = get_github_client()
            self.context["repo_full_name"] = (
                f"{self.context['repo_owner']}/{self.context['repo_name']}"
            )

            repo = gh.get_repo(
                f"{self.context['repo_owner']}/{self.context['repo_name']}"
            )
            self.context["base"] = repo.default_branch
            log_key_value("Default branch", self.context["base"])
            log_key_value("API Mode", "Gitea" if is_gitea_mode() else "GitHub")
        except Exception as e:
            log_error(e, "Failed to get default branch, using 'main'")
            self.context["base"] = "main"
```

## Environment Configuration

### For GitHub (Default)
```bash
export GITHUB_TOKEN="your_github_token"
# USE_GITEA is not set or set to 'false'
```

### For Gitea
```bash
export USE_GITEA="true"
export GITEA_URL="http://your-gitea-instance:3000"
export GITEA_TOKEN="your_gitea_token"  # or use GITHUB_TOKEN
```

## Testing the Migration

1. **Test with GitHub:**
   ```bash
   export GITHUB_TOKEN="your_token"
   python your_workflow.py
   ```

2. **Test with Gitea:**
   ```bash
   export USE_GITEA="true"
   export GITEA_URL="http://localhost:3000"
   export GITHUB_TOKEN="your_token"
   python your_workflow.py
   ```

3. **Run the shim test:**
   ```bash
   cd gitea-shim/python
   python test_shim.py
   ```

## Common Issues and Solutions

### Issue: Import Error
**Error:** `ModuleNotFoundError: No module named 'gitea_shim'`

**Solution:** Check that the path to the gitea-shim is correct in your import statement.

### Issue: Gitea Connection Failed
**Error:** `Connection refused` or `404 Not Found`

**Solution:** 
1. Verify `GITEA_URL` is correct
2. Ensure Gitea is running
3. Check that your token has the right permissions

### Issue: Repository Not Found
**Error:** `Repository owner/repo not found`

**Solution:**
1. Verify the repository exists in your Gitea instance
2. Check that your token has access to the repository
3. Ensure the repository name is correct (case-sensitive)

### Issue: Authentication Failed
**Error:** `401 Unauthorized`

**Solution:**
1. Verify your token is valid
2. Check token permissions
3. Ensure `GITHUB_TOKEN` or `GITEA_TOKEN` is set correctly

## Benefits of Migration

1. **Code Reusability:** Same code works with both GitHub and Gitea
2. **Easy Testing:** Test against Gitea locally, deploy to GitHub
3. **Flexibility:** Switch between APIs without code changes
4. **Consistency:** Same interface regardless of backend
5. **Future-Proof:** Easy to add support for other Git hosting platforms

## Support

If you encounter issues during migration:

1. Check the test output: `python test_shim.py`
2. Verify environment variables are set correctly
3. Check the logs for detailed error messages
4. Ensure Gitea is running and accessible