# GitLab to Forgejo Attachment Migrator

This script migrates attachments from GitLab issues to their corresponding Forgejo issues, addressing the limitation in Forgejo's GitLab importer that doesn't handle attachments.

## Problem Solved

The standard Forgejo GitLab importer only imports metadata (issues, comments, etc.) but **does not import attachments**. This leaves issues with broken image links and missing files, making visual content unusable after migration.

## How It Works

1. **Downloads attachments** from GitLab issues using URL scraping (since GitLab API doesn't provide attachment download endpoints)
2. **Uploads attachments** to Forgejo using the API
3. **Updates issue content** by replacing old GitLab URLs with new Forgejo URLs
4. **Handles all content** including issue descriptions and comments

## Installation

```bash
pip install -r requirements.txt
```

## Configuration

Set the following environment variables:

```bash
export GITLAB_TOKEN="your_gitlab_api_token"
export FORGEJO_TOKEN="your_forgejo_api_token"
export GITLAB_PROJECT_ID="group/project"  # or numeric ID
export FORGEJO_OWNER="your_username"
export FORGEJO_REPO="your_repo_name"

# Optional (defaults shown)
export GITLAB_URL="https://gitlab.com"
export FORGEJO_URL="https://codeberg.org"
```

### Getting API Tokens

**GitLab Token:**
1. Go to GitLab → User Settings → Access Tokens
2. Create token with `api` scope
3. Copy the token value

**Forgejo Token:**
1. Go to Forgejo → User Settings → Applications
2. Generate New Token with repository access
3. Copy the token value

## Usage

```bash
python gitlab_to_forgejo_attachments.py
```

## Example Migration

For an issue like [this Codeberg issue](https://codeberg.org/gridhead/requests-test/issues/100) that contains logo design sketches and images, the script will:

1. Find all image URLs in the issue content
2. Download each attachment from GitLab
3. Upload to Forgejo
4. Replace URLs like `/uploads/abc123.../logo.png` with new Forgejo URLs
5. Update the issue description with the new URLs

## Output

The script provides detailed logging and final statistics:

```
2025-11-21 10:30:15 - INFO - Starting GitLab to Forgejo attachment migration...
2025-11-21 10:30:15 - INFO - GitLab: https://gitlab.com/my-project
2025-11-21 10:30:15 - INFO - Forgejo: https://codeberg.org/user/repo
2025-11-21 10:30:16 - INFO - Found 25 issues in project my-project
2025-11-21 10:30:17 - INFO - Processing GitLab issue #1: Logo design discussion
2025-11-21 10:30:18 - INFO - Found 4 attachments in issue #1
2025-11-21 10:30:19 - INFO - Downloaded attachment: logo-sketch-1.png
2025-11-21 10:30:20 - INFO - Uploaded logo-sketch-1.png to Forgejo: https://codeberg.org/attachments/...
...
2025-11-21 10:35:22 - INFO - Migration completed!
2025-11-21 10:35:22 - INFO - Issues processed: 25
2025-11-21 10:35:22 - INFO - Attachments migrated: 47
2025-11-21 10:35:22 - INFO - Attachments failed: 2
2025-11-21 10:35:22 - INFO - Issues updated: 12
```

## Limitations

- Only works with issues that have already been migrated (metadata must exist in Forgejo)
- Assumes 1:1 mapping between GitLab and Forgejo issue numbers
- GitLab attachment URLs must follow standard `/uploads/` pattern
- Requires API access to both GitLab and Forgejo instances

## Use Cases

Perfect for:
- Post-migration cleanup when standard Forgejo import missed attachments
- Retroactive fixing of broken image links in migrated repositories
- Visual content preservation (logos, screenshots, diagrams, etc.)
- Issues with embedded images that are essential for understanding context

## Security Notes

- Uses authenticated API calls for both GitLab and Forgejo
- Downloads files temporarily in memory (no local file storage)
- Respects API rate limits with proper error handling
- Tokens should have minimal required permissions (read for GitLab, write for Forgejo)