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:

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:

from github import Github
gh = Github(os.getenv("GITHUB_TOKEN"))

After:

gh = get_github_client()

Step 3: Add Logging (Optional)

Add logging to see which API you're using:

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

Complete Example

Before Migration

"""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

"""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)

export GITHUB_TOKEN="your_github_token"
# USE_GITEA is not set or set to 'false'

For Gitea

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:

   export GITHUB_TOKEN="your_token"
   python your_workflow.py
   

2. Test with Gitea:

   export USE_GITEA="true"
   export GITEA_URL="http://localhost:3000"
   export GITHUB_TOKEN="your_token"
   python your_workflow.py
   

3. Run the shim test:

   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