- tutorial

1.17 breaking changes episode 2: preserving a custom gitconfig

2022-07-20T00:00:00+00:00

On June 21st, 2022 1.17.0-rc1 was published and the location of the gitconfig file moved to a new location, which required manual intervention</a>. This change impacted a large number of Gitea installations because the docker image tag latest was set to 1.17.0-rc1</a> by accident. As a result, about 10,000 pulls per hour from the docker hub got the release candidate instead of the expected stable version.

Unfortunately moving the git home directory in 1.17.0-rc1 was implemented in way that created a security problem. The fix that was merged in Gitea</a> to fix it requires moving the gitconfig file and was released July 19th, 2022 in 1.17.0-rc2.

This would have been a minor inconvenience if it only has an impact on adventurous people trying the release candidate in a test environment. But since all Gitea production installations based on the latest tag were inadvertently upgraded to 1.17.0-rc1, the admins who moved their custom .gitconfig will need to move it one more time when upgrading to 1.17.0-rc2.

In 1.17.0-rc2, a custom .gitconfig must be moved manually to the new git home directory</a> as follows:

Figure out the directory where $HOME/.gitconfig</code> must be moved by running the doctor</a>:</li> </ul> $ gitea --work-path /app/gitea -c /data/gitea/conf/app.ini doctor [1] Check paths and basic configuration - [I] Configuration File Path: "/data/gitea/conf/app.ini" - [I] Repository Root Path: "/data/git/repositories" - [I] Data Root Path: "/data/gitea" - [I] Custom File Root Path: "/data/gitea" - [I] Work directory: "/app/gitea" - [I] Log Root Path: "/data/gitea/log" OK </code></pre> Copy the $HOME/.gitconfig</code> file to the Data Root Path/home (which is /data/gitea/home</code> in the example above).</li> </ul>

1.17 breaking changes episode 1: preserving a custom gitconfig 2022-06-22T00:00:00+00:00 Before version 1.17, when Gitea needed to change the git configuration</a>, it modified the $HOME/.gitconfig</code> file. For instance it would set core.quotePath to false</a>: [core] quotePath = false </code></pre> When installing Gitea from docker</a> or rootless</a> or even from binary</a> this $HOME/.gitconfig</code> file belongs to a user that is dedicated to Gitea</a> and not used by anyone else. However, if an Gitea installation was done differently and $HOME/.gitconfig</code> has been customized because it is shared by a user or another application, there is a good chance that manual modifications were done such as: [user] name = Jane Doe email = jane@doe.com </code></pre> It is also possible that the file was modified manually by the Gitea admin for other reasons. In both there is a potential for breakage when upgrading to Gitea >= 1.17 because the location of the file changed. It must be moved manually to the new location as follows: Figure out the directory where $HOME/.gitconfig</code> must be moved by running the doctor</a>:</li> </ul> $ gitea --work-path /app/gitea -c /data/gitea/conf/app.ini doctor [1] Check paths and basic configuration - [I] Configuration File Path: "/data/gitea/conf/app.ini" - [I] Repository Root Path: "/data/git/repositories" - [I] Data Root Path: "/data/gitea" - [I] Custom File Root Path: "/data/gitea" - [I] Work directory: "/app/gitea" - [I] Log Root Path: "/data/gitea/log" OK </code></pre> Copy the $HOME/.gitconfig</code> file to the Repository Root Path (which is /data/git/repositories</code> in the example above).</li> </ul> The reason why this breaking change was introduced is to workaround a rare problem</a> impacting Gitea installations relying on networked volumes. [tutorial] A gentle introduction to the gitea doctor 2022-06-14T00:00:00+00:00 While helping people with their upgrades in the Gitea forum</a> or at the Gna! clinic</a>, I realized that few Gitea admins know about the gitea doctor</code></a> command and decided to write this blog post as a gentle introduction. An apple a day keeps the doctor away#</a > </h3> Or in our case, Gitea versions below 1.11.5</a>. Since then, the gitea doctor</code> is available and is designed to run against a specific Gitea version. It would not be a good idea to try to run the doctor from Gitea 1.16 to verify the sanity of a Gitea 1.2 instance: it will be confused by how the database is organized and a number of other details. Historical fun fact: the gitea doctor</code> was backported to Gitea 1.10.5</a> and Gitea 1.10.6</a> and may be of help if you run this particular version and are facing the problem that motivated the backport. With each version gitea doctor</code> improves and gains new capabilities. For instance, in Gitea 1.17 it becomes aware of orphaned pull requests</a> and is able to fix them. If such a problem exists in Gitea 1.16, it does not know about it. Calling the doctor#</a > </h3> In the following, examples are based on a Gitea 1.16.8 instance you can run as follows: $ docker run --name gitea -p 3000:3000 -e GITEA__security__INSTALL_LOCK=true -d gitea/gitea:1.16.8-rootless $ docker exec gitea gitea admin user create --admin --username root --password admin1234 --email root@example.com $ docker exec gitea mkdir /var/lib/gitea/data/log </code></pre> And then you can go to the web interface</a> to create a test</code> repository, with an initial README.md</code> file. When this is done the doctor can be called as follows: $ docker exec gitea gitea doctor --all [1] Check paths and basic configuration - [I] Configuration File Path: "/etc/gitea/app.ini" - [I] Repository Root Path: "/var/lib/gitea/git/repositories" - [I] Data Root Path: "/var/lib/gitea" - [I] Custom File Root Path: "/var/lib/gitea/custom" - [I] Work directory: "/var/lib/gitea" - [I] Log Root Path: "/var/lib/gitea/data/log" OK [2] Check if there is garbage storage files OK [3] Check Database Version OK [4] Check consistency of database OK [5] Check if user with wrong type exist OK [6] Check if OpenSSH authorized_keys file is up-to-date OK [7] Check if SCRIPT_TYPE is available - [I] ScriptType bash is on the current PATH at /bin/bash OK [8] Check if hook files are up-to-date and executable OK [9] Recalculate Stars number for all user OK [10] Check old archives - [I] 0 old archives in repository need to be deleted OK [11] Enable push options - [I] Checked 1 repositories, 0 need updates. OK [12] Check for incorrectly dumped repo_units (See #16961) - [W] Found 0 broken repo_units OK [13] Recalculate merge bases - [W] 0 PRs with incorrect mergebases of 0 PRs total in 1 repos OK [14] Check git-daemon-export-ok files - [I] Checked 1 repositories, 0 need updates. </code></pre> What does the doctor know?#</a > </h3> Although the doctor</code> can be compared to fsck(8)</a>, it does not know everything. It took decades for fsck</code> to become the ultimate authority on finding problems on file systems and reliably fixing them without losing data. Nowadays, only a handful of people in the world are brave enough to manually attempt a file system recovery when fsck</code> cannot recover from a data loss. The first doctor</code> version is two years old and Gitea admins are still routinely running SQL queries against the database or moving files around when trying to figure out why a Gitea instance is not behaving as it should. It is however worth checking if the doctor does not already have a solution by listing all it can do: $ docker exec gitea gitea doctor --list Default Name Title * paths Check paths and basic configuration storages Check if there is garbage storage files * check-db-version Check Database Version check-db-consistency Check consistency of database * check-user-type Check if user with wrong type exist * authorized-keys Check if OpenSSH authorized_keys file is up-to-date script-type Check if SCRIPT_TYPE is available hooks Check if hook files are up-to-date and executable recalculate-stars-number Recalculate Stars number for all user check-old-archives Check old archives enable-push-options Enable push options fix-broken-repo-units Check for incorrectly dumped repo_units (See #16961) recalculate-merge-bases Recalculate merge bases check-git-daemon-export-ok Check git-daemon-export-ok files </code></pre> And then call the check</code> that looks interesting: $ docker exec gitea gitea doctor --run authorized-keys [1] Check if OpenSSH authorized_keys file is up-to-date OK </code></pre> The challenge is to figure out which check</code> does what and at the moment the best source of information is ... the sources</a> themselves. The doctor.go</a> command is the entry point and the doctor directory</a> contains the rest. Some checks</code> are straightforward to understand, even if you do not know Go, such as the authorized-keys check</a>. Others are much more involved and your best chance is to ask the Gitea chatroom</a> for help. Is it going to hurt?#</a > </h3> By default the doctor (very much like fsck -N</code>) only performs non destructive checks and displays diagnostics, with an indication of how serious the problem is. In the example above, there only are lines with [I] (which indicates an information) and [W] which indicates a warning that can be ignored but may be worth looking into. Those two warnings are actually just informational and should be labelled as [I], which has been fixed</a> in a more recent version of the doctor. Now let's do something bad: remove the permissions from a hook in our repository: $ docker exec gitea chmod -x /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive </code></pre> Run the doctor with the check</code> supposed to find that out: $ docker exec gitea gitea doctor --run hooks [1] Check if hook files are up-to-date and executable - [W] old hook file /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive is not executable </code></pre> Ask it to fix this with the --fix</code> flag: $ docker exec gitea gitea doctor --run hooks --fix [1] Check if hook files are up-to-date and executable - [W] Regenerated hooks for root/test - [W] old hook file /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive is not executable </code></pre> And run it one last time to check all is well: $ docker exec gitea gitea doctor --run hooks [1] Check if hook files are up-to-date and executable OK </code></pre> Even when the doctor is unable to fix a problem, it can help by showing extensive debug output which can be found, by default, in the doctor.log</code> file in the directory from which it runs. Or it can be displayed on the standard output with --log-file -</code>, which is most convenient when running in docker. Going further#</a > </h3> If that was helpful to you, I would very much appreciate if you send me a message on Mastodon</a>. It will encourage me to write more blog posts to share what I learn about Gitea. Even better: you could send a pull request</a> to improve the doctor and help it mature.