Gitea Migration Tool

A Python 3 tool for migrating git repositories to Gitea. This tool can migrate a single repository or recursively search a directory for multiple repositories and migrate them all.

Features

• ✅ Migrate single repositories or multiple repositories recursively
• ✅ Automatically create repositories in Gitea if they don't exist
• ✅ Handle conflicts when repositories already exist in Gitea
• ✅ Support for both SSH and HTTPS remotes
• ✅ Interactive conflict resolution prompts
• ✅ Non-interactive mode for automation

Requirements

• Python 3.8 or higher
• Git installed on your local machine
• A Gitea account with a valid personal access token
• SSH access to your Gitea server (if using SSH remotes)

Installation

From Source

# Clone the repository
git clone <repository-url>
cd gitea

# Install in development mode
pip install -e .

# Or install normally
pip install .

Using pip (if published)

pip install gitea-migrate

Configuration

The tool uses environment variables for configuration. Set the following:

export GITEA_HOST="gitea.example.com"        # Gitea hostname (required)
export GITEA_USER="your_username"            # Gitea username (required)
export GITEA_TOKEN="your_access_token"       # Personal access token (required)
export GITEA_USE_SSH="true"                  # Use SSH URLs (default: true)
export GITEA_SSH_PORT="30009"                # Custom SSH port (optional, if not standard port 22)

You can also override these values using command-line arguments (see Usage below).

Creating a Gitea Personal Access Token

1. Log in to your Gitea instance
2. Go to Settings → Applications → Generate New Token
3. Give it a name (e.g., "migration-tool")
4. Select the repo scope (or write:repository permission)
5. Copy the token and set it in GITEA_TOKEN

Usage

Basic Usage

Migrate the current directory (single repository):

gitea-migrate .

Migrate a specific repository:

gitea-migrate /path/to/repository

Migrate all repositories in a directory recursively:

gitea-migrate /path/to/parent/dir --recursive

Migrate multiple specific repositories:

gitea-migrate /path/to/repo1 /path/to/repo2 /path/to/repo3

Migrate a mix of repositories and directories:

gitea-migrate /path/to/repo1 /path/to/dir1 /path/to/repo2 --recursive

Command-Line Options

positional arguments:
  paths                 Path(s) to repository/repositories or directory/directories to migrate

optional arguments:
  -h, --help            Show help message
  -r, --recursive       Recursively search for repositories in directory
  --host HOST           Gitea hostname (overrides GITEA_HOST env var)
  --username USERNAME   Gitea username (overrides GITEA_USER env var)
  --token TOKEN         Gitea personal access token (overrides GITEA_TOKEN env var)
  --no-ssh              Use HTTPS instead of SSH
  --ssh-port PORT       Custom SSH port for git operations (overrides GITEA_SSH_PORT env var)
  --non-interactive     Non-interactive mode (abort on conflicts)

Examples

Migrate current directory with HTTPS:

GITEA_USE_SSH=false gitea-migrate .

Migrate with custom SSH port:

GITEA_SSH_PORT=30009 gitea-migrate .
# or
gitea-migrate . --ssh-port 30009

Migrate all repos in a directory non-interactively:

gitea-migrate /path/to/repos --recursive --non-interactive

Override configuration via command line:

gitea-migrate . --host gitea.example.com --username myuser --token mytoken --ssh-port 30009

Conflict Resolution

When a repository already exists in Gitea, the tool will prompt you to choose an action:

1. Abort (default): Skip this repository and continue with others
2. Overwrite remote: Delete the remote repository and recreate it, then push local content
3. Overwrite local: Reset the local repository to match the remote (discards local changes)

In non-interactive mode (--non-interactive), the tool will automatically abort on conflicts.

How It Works

1. Repository Detection: The tool checks if the specified path is a git repository, or searches recursively for git repositories in a directory.

2. Gitea Check: For each repository, it checks if a repository with the same name already exists in Gitea.

3. Repository Creation: If the repository doesn't exist, it creates it in Gitea using the API.

4. Remote Setup: It replaces the origin remote (or creates it if it doesn't exist) with the Gitea repository URL.

5. Push: It pushes the default branch (main or master) to Gitea.

6. Conflict Handling: If the repository exists, it prompts for conflict resolution (unless in non-interactive mode).

Migration Summary

When migrating multiple repositories, the tool displays a summary:

============================================================
Migration Summary
============================================================
Total repositories: 5
Successful: 4
Failed: 1
============================================================

Troubleshooting

"Gitea host is required" Error

Make sure you've set the GITEA_HOST environment variable or use the --host argument.

"Failed to create repository" Error

• Verify your Gitea token has the correct permissions
• Check that the repository name is valid (no special characters)
• Ensure you have permission to create repositories

"Failed to push" Error

• Verify SSH access to your Gitea server (if using SSH)
• Check that your SSH key is added to Gitea
• For HTTPS, ensure your token has push permissions

Repository Not Found

If you're trying to migrate a repository that doesn't exist locally, make sure:

• The path is correct
• The directory contains a .git folder
• You have read permissions to the directory

License

MIT License. Use freely and modify as needed.