Select Page

0. Back up Gogs and dump the database

You’ll want to grab a database dump before you continue.

gogs backup doesn’t perform a database dump, at least not in the traditional sense. Instead, it queries the database for information and stores it in a database-agnostic JSON format.

Perform a mysqldump or pg_dump in addition to a gogs backup before you start.

1. Follow the official migration document

Upgrade from Gogs” follow its guidance to get your files in the right places. With one important caveat: do not run gitea web yet. We need to get the data in order first.

2. Override the database schema version

Gogs and Gitea diverged some time ago, now, so you’ll need to back the schema version down to 13 for Gitea’s migrations to run properly.

Connect to your Gogs database and run:

UPDATE version SET version=13;

3. Delete pre- and post-receive webhooks

Recurse through your gitea-repositories folder and delete all of Gogs’s webhooks. If you don’t do this, you’ll end up unable to git pull or git push with perplexing “server gave HTTP response to HTTPS client” or 500 server errors.

# Run in your gitea-repositories folder
find . -type f \( -name pre-receive -o -name post-receive \) -exec rm -f {} \;

4. Download every major Gitea version between 1.0.x and current

To make this process a bit less tedious, here’s some shell.

for version in 1.1.4 1.2.3 1.3.3 1.4.3 1.5.3 1.6.4 1.7.6 1.8.3 1.9.6 1.10.6 1.11.8 1.12.6
do
    wget -O gitea-$version https://dl.gitea.io/gitea/$version/gitea-$version-linux-amd64
    chmod +x gitea-$version
done

5. Run each Gitea version in sequence

Keep your Gitea logs open for this process and watch for any errors. If you’re not sure where Gitea is logging to, check your app.ini.

For each major version of Gitea, run ./gitea-$version web -c /path/to/app.ini. Wait for any database migration steps to finish and load the UI in your browser. At a minimum, confirm that you can log in, view your repositories, view a repository’s file structure, and finally view the contents of a file in one of your repositories.

If you get into a bad state and need to start over, drop the database and restore from your database dump. The migration process doesn’t appear to touch the repositories, so a full repository wipe and gogs restore probably aren’t needed.

6. Manual database fixes

By now you should have a mostly functional installation of Gitea. Your repositories, pull requests, issues, and such should all be reachable, but I encountered a few additional quirks that needed fixing.

Performing a git push resulted in a missing column error, which was fixed by running:

ALTER TABLE repository ADD COLUMN IF NOT EXISTS is_bare BOOLEAN;

On Gitea 1.12.x, the repository filter on the home page didn’t work on account of the repositories missing an is_archived value. Since this was a fresh migration, I set all my repositories to be unarchived:

UPDATE repository SET is_archived=false;

You may have to run this once you hit the 1.2.3 version of Gitea or you will maybe get some 404 errors while trying to view the repos

insert into repo_unit (`repo_id`, `type`, `index`, `config`) 
select repository.id, types.*, '{}' from repository
left join repo_unit on repository.id=repo_id 
left join (
  select 1 as col1, 1 as col2
  UNION ALL select 2,2
  UNION ALL select 3,3
  UNION ALL select 4,4
  UNION ALL select 5,5) as types on (1=1)
where repo_id is null;

7. Enjoy Gitea!