Migrating Gitea from one instance to another is essentially a backup and restore operation. Since Gitea stores its data in two main places—the database and the filesystem—the process involves moving both while keeping them in sync.

The most reliable method is using Gitea’s built-in dump command, which packages everything into a single zip file.

Method 1: The “Dump & Restore” (Recommended)

This method is the cleanest because it ensures all metadata (issues, pull requests, users) is captured along with the code.

1. Create the Backup (Old Instance)

On your current server, run the dump command as the user that runs Gitea (usually git).

Bash

# Switch to the gitea/git user
su - git

# Run the dump (this creates a .zip file in the current directory)
./gitea dump -c /path/to/app.ini

This zip file contains:

  • gitea-db.sql: The database export.

  • data/: Attachments, avatars, and LFS files.

  • repos/: All your Git repositories.

  • app.ini: Your configuration.

2. Prepare the New Instance

Install Gitea on the new server using the same version as the old one. Once installed, do not run the initial setup wizard. Stop the Gitea service before proceeding.

3. Restore the Data (New Instance)

Transfer the zip file to your new server and extract it. You will then manually move the files to their new home:

  1. Move Files: Place the data and repos folders into the directory defined in your new Gitea installation (usually /var/lib/gitea/).

  2. Restore Database: * PostgreSQL/MySQL: Use the standard tools to import the .sql file (e.g., psql -d gitea < gitea-db.sql).

    • SQLite: Simply replace the gitea.db file with the one from the backup.

  3. Update Config: Copy the app.ini and update any paths or database credentials that might have changed on the new server.

4. Final Maintenance

After starting the new Gitea service, you must regenerate the Git hooks to ensure the repository paths are correct.

Bash

./gitea admin regenerate hooks

Method 2: Manual Migration (Docker)

If you are using Docker, the process is even simpler because the environment is encapsulated.

  1. Stop the Gitea container on the old server.

  2. Copy the entire mapped volume directory (usually where your docker-compose.yml and data folder live) to the new server using rsync or scp.

    Bash

    rsync -avz /path/to/gitea-docker/ user@new-server:/path/to/gitea-docker/

  3. Update the docker-compose.yml if the IP address or domain has changed.

  4. Start the container on the new server: docker-compose up -d.

Important Migration Checklist

  • Version Matching: Ensure the Gitea version on the new server matches the old one exactly. You can upgrade after a successful migration.

  • Permissions: After moving files manually, ensure the git user owns everything: chown -R git:git /var/lib/gitea.

  • LFS: If you use Git LFS, ensure the lfs directory inside data is moved; otherwise, your large files will be corrupted.

  • SSH Keys: If you move to a new server, the SSH host key will change. Users will get a “Remote Host Identification Has Changed” warning until they update their known_hosts.

Would you like me to provide the specific commands for restoring the database based on whether you’re using PostgreSQL, MySQL, or SQLite?