suyu-v0.0.4/scripts/TROUBLESHOOTING.md

Troubleshooting Guide - Forgejo to GitHub Issue Sync

This guide helps resolve common issues with the Forgejo to GitHub issue synchronization.

Common Issues

1. 403 Forbidden Error

Error Message:

Error fetching issues from Forgejo: 403 Client Error: Forbidden for url: https://git.suyu.dev/suyu/suyu/issues

Causes & Solutions:

1. Using web scraping URL instead of API URL

   • ❌ Wrong: https://git.suyu.dev/suyu/suyu/issues
   • ✅ Correct: https://git.suyu.dev/api/v1/repos/suyu/suyu/issues

2. Repository requires authentication

   • Set the FORGEJO_TOKEN environment variable
   • Generate a token in Forgejo: Settings → Applications → Generate New Token

3. Repository is private or restricted

   • Verify you have access to the repository
   • Check if the repository URL is correct

2. No Issues Found

Error Message:

No issues found on Forgejo or failed to fetch issues

Solutions:

1. Check the repository has issues

   • Visit the Forgejo repository directly
   • Verify there are open issues

2. Verify API endpoint

   • Test with: curl https://git.suyu.dev/api/v1/repos/suyu/suyu/issues
   • Should return JSON array of issues

3. Check issue state filter

   • The script only syncs "open" issues by default
   • Modify SYNC_STATES in config.py to include "closed" if needed

3. GitHub API Errors

Error Message:

Failed to create issue 'Title': 401 Unauthorized

Solutions:

1. Invalid GitHub token

   • Verify GITHUB_TOKEN is set correctly
   • Token needs repo scope for private repos, public_repo for public repos

2. Rate limiting

   • The script includes automatic rate limiting
   • If you hit limits, wait and try again

4. Duplicate Issues

Issue: Issues are being created multiple times

Solutions:

1. Check duplicate detection logic

   • Script checks for both original and prefixed titles
   • Verify existing issues are being fetched correctly

2. Manual cleanup

   • Close duplicate issues manually
   • The script will skip them on next run

Testing Steps

1. Test Forgejo connection:

   python scripts/test_forgejo_connection.py
   

2. Test with limited issues:

   • Set MAX_ISSUES_PER_RUN = 1 in config.py
   • Run the script to test with just one issue

3. Check GitHub API access:

   curl -H "Authorization: Bearer $GITHUB_TOKEN" \
        https://api.github.com/repos/owner/repo/issues
   

Getting Help

If you're still experiencing issues:

1. Check the GitHub Actions logs for detailed error messages
2. Run the standalone script locally for easier debugging
3. Verify all environment variables are set correctly
4. Test API endpoints manually with curl

Useful Commands

Test Forgejo API:

curl "https://git.suyu.dev/api/v1/repos/suyu/suyu/issues?per_page=1"

Test GitHub API:

curl -H "Authorization: Bearer $GITHUB_TOKEN" \
     "https://api.github.com/repos/$GITHUB_REPOSITORY/issues?per_page=1"

Check environment variables:

echo "FORGEJO_URL: $FORGEJO_URL"
echo "GITHUB_REPOSITORY: $GITHUB_REPOSITORY"
echo "GITHUB_TOKEN: ${GITHUB_TOKEN:0:10}..." # Only show first 10 chars