<contenttype="html"><p>On June 21st, 2022 1.17.0-rc1 was published and the location of the gitconfig file moved to a new location, <a href="2022-06-23-1.17-breaking-episode-1">which required manual intervention</a>. This change impacted a large number of Gitea installations because the docker image tag <strong>latest</strong><a href="https://mastodon.online/@hostea/108514134565401798">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.</p>
<p>Unfortunately moving the git home directory in 1.17.0-rc1 was implemented in way that created a security problem. The <a href="https://github.com/go-gitea/gitea/pull/20114">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.</p>
<p>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 <strong>latest</strong> 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.</p>
<p>In 1.17.0-rc2, a custom .gitconfig must be moved manually to the <a href="https://docs.gitea.io/en-us/config-cheat-sheet/#git-git">new git home directory</a> as follows:</p>
<li>Figure out the directory where <code>$HOME/.gitconfig</code> must be moved by <a href="https://gna.org/blog/gentle-introduction-to-the-doctor/">running the doctor</a>:</li>
<li>Copy the <code>$HOME/.gitconfig</code> file to the <strong>Data Root Path</strong>/home (which is <code>/data/gitea/home</code> in the example above).</li>
<contenttype="html"><p>Before version 1.17, when Gitea needed to change the <a href="https://git-scm.com/docs/git-config">git configuration</a>, it modified the <code>$HOME/.gitconfig</code> file. For instance it would <a href="https://github.com/go-gitea/gitea/blob/release/v1.16/modules/git/git.go#L174-L177">set core.quotePath to false</a>:</p>
<p>When installing Gitea <a href="https://docs.gitea.io/en-us/install-with-docker/">from docker</a> or <a href="https://docs.gitea.io/en-us/install-with-docker-rootless/">rootless</a> or even <a href="https://docs.gitea.io/en-us/install-from-binary/">from binary</a> this <code>$HOME/.gitconfig</code> file belongs to a user that is <a href="https://docs.gitea.io/en-us/install-from-binary/#prepare-environment">dedicated to Gitea</a> and not used by anyone else.</p>
<p>However, if an Gitea installation was done differently and <code>$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:</p>
<p>It is also possible that the file was modified manually by the Gitea admin for other reasons. In both there is a <strong>potential for breakage when upgrading to Gitea &gt;= 1.17 because the location of the file changed</strong>. It must be moved manually to the new location as follows:</p>
<li>Figure out the directory where <code>$HOME/.gitconfig</code> must be moved by <a href="https://gna.org/blog/gentle-introduction-to-the-doctor/">running the doctor</a>:</li>
<li>Copy the <code>$HOME/.gitconfig</code> file to the <strong>Repository Root Path</strong> (which is <code>/data/git/repositories</code> in the example above).</li>
<p>The reason why this breaking change was introduced is to workaround <a href="https://gna.org/blog/unsafe-repository-is-owned-by-someone-else/">a rare problem</a> impacting Gitea installations relying on networked volumes.</p>
<contenttype="html"><p>While helping people with their upgrades <a href="https://discourse.gitea.io/t/migration-from-1-2-to-1-16-8/5309">in the Gitea forum</a> or <a href="https://forum.gna.org/t/gitea-upgrade-from-1-14-1-to-1-16-8/90">at the Gna! clinic</a>, I realized that few Gitea admins know about the <a href="https://docs.gitea.io/en-us/command-line/#doctor"><code>gitea doctor</code></a> command and decided to write this blog post as a gentle introduction.</p>
<h3 id="an-apple-a-day-keeps-the-doctor-away">An apple a day keeps the doctor away<a class="zola-anchor" href="#an-apple-a-day-keeps-the-doctor-away" aria-label="Anchor link for: an-apple-a-day-keeps-the-doctor-away"
<p>Or in our case, Gitea versions <a href="https://github.com/go-gitea/gitea/blob/v1.11.5/cmd/doctor.go">below 1.11.5</a>. Since then, the <code>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 <code>gitea doctor</code> was backported to <a href="https://github.com/go-gitea/gitea/blob/v1.10.5/cmd/doctor.go">Gitea 1.10.5</a> and <a href="https://github.com/go-gitea/gitea/blob/v1.10.6/cmd/doctor.go">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.</p>
<p>With each version <code>gitea doctor</code> improves and gains new capabilities. For instance, in Gitea 1.17 it becomes aware of <a href="https://github.com/go-gitea/gitea/pull/19731">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.</p>
<h3 id="calling-the-doctor">Calling the doctor<a class="zola-anchor" href="#calling-the-doctor" aria-label="Anchor link for: calling-the-doctor"
<p>And then you can go to the <a href="https://127.0.0.1:3000/">web interface</a> to create a <code>test</code> repository, with an initial <code>README.md</code> file. When this is done the doctor can be called as follows:</p>
</span><span style="color:#bf616a;">[7]</span><span> Check if SCRIPT_TYPE is available
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>I</span><span style="color:#b48ead;">]</span><span> ScriptType bash is on the current PATH at /bin/bash
</span><span style="color:#bf616a;">[10]</span><span> Check old archives
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>I</span><span style="color:#b48ead;">]</span><span> 0 old archives in repository need to be deleted
</span><span style="color:#bf616a;">[12]</span><span> Check for incorrectly dumped repo_units (See </span><span style="color:#65737e;">#16961)
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>W</span><span style="color:#b48ead;">]</span><span> Found 0 broken repo_units
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>W</span><span style="color:#b48ead;">]</span><span> 0 PRs with incorrect mergebases of 0 PRs total in 1 repos
<h3 id="what-does-the-doctor-know">What does the doctor know?<a class="zola-anchor" href="#what-does-the-doctor-know" aria-label="Anchor link for: what-does-the-doctor-know"
<p>Although the <code>doctor</code> can be compared to <a href="https://en.wikipedia.org/wiki/Fsck">fsck(8)</a>, it does not know everything. It took decades for <code>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 <code>fsck</code> cannot recover from a data loss.</p>
<p>The first <code>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:</p>
</span><span style="color:#bf616a;">Default</span><span> Name Title
</span><span style="color:#bf616a;">*</span><span> paths Check paths and basic configuration
</span><span></span><span style="color:#bf616a;">storages</span><span> Check if there is garbage storage files
</span><span style="color:#bf616a;">*</span><span> check-db-version Check Database Version
</span><span></span><span style="color:#bf616a;">check-db-consistency</span><span> Check consistency of database
</span><span style="color:#bf616a;">*</span><span> check-user-type Check if user with wrong type exist
</span><span style="color:#bf616a;">*</span><span> authorized-keys Check if OpenSSH authorized_keys file is up-to-date
</span><span></span><span style="color:#bf616a;">script-type</span><span> Check if SCRIPT_TYPE is available
</span><span></span><span style="color:#bf616a;">hooks</span><span> Check if hook files are up-to-date and executable
</span><span></span><span style="color:#bf616a;">recalculate-stars-number</span><span> Recalculate Stars number for all user
</span><span></span><span style="color:#bf616a;">check-old-archives</span><span> Check old archives
</span><span></span><span style="color:#bf616a;">fix-broken-repo-units</span><span> Check for incorrectly dumped repo_units (See </span><span style="color:#65737e;">#16961)
<p>The challenge is to figure out which <code>check</code> does what and at the moment the best source of information is ... <a href="https://github.com/go-gitea/gitea/tree/v1.16.8">the sources</a> themselves. The <a href="https://github.com/go-gitea/gitea/blob/v1.16.8/cmd/doctor.go">doctor.go</a> command is the entry point and <a href="https://github.com/go-gitea/gitea/tree/v1.16.8/modules/doctor">the doctor directory</a> contains the rest.</p>
<p>Some <code>checks</code> are straightforward to understand, even if you do not know Go, such as <a href="https://github.com/go-gitea/gitea/blob/v1.16.8/modules/doctor/authorizedkeys.go">the authorized-keys check</a>. Others are much more involved and your best chance is to <a href="https://matrix.to/#/#gitea:matrix.org">ask the Gitea chatroom</a> for help.</p>
<h3 id="is-it-going-to-hurt">Is it going to hurt?<a class="zola-anchor" href="#is-it-going-to-hurt" aria-label="Anchor link for: is-it-going-to-hurt"
<p>By default the doctor (very much like <code>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 <strong>[I]</strong> (which indicates an information) and <strong>[W]</strong> 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 <strong>[I]</strong>, <a href="https://github.com/go-gitea/gitea/pull/19836">which has been fixed</a> in a more recent version of the doctor.</p>
<p>Now let's do something bad: remove the permissions from a hook in our repository:</p>
</span><span style="color:#bf616a;">[1]</span><span> Check if hook files are up-to-date and executable
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>W</span><span style="color:#b48ead;">]</span><span> old hook file /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive is not executable
</span><span style="color:#bf616a;">[1]</span><span> Check if hook files are up-to-date and executable
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>W</span><span style="color:#b48ead;">]</span><span> Regenerated hooks for root/test
</span><span></span><span style="color:#bf616a;">- </span><span style="color:#b48ead;">[</span><span>W</span><span style="color:#b48ead;">]</span><span> old hook file /var/lib/gitea/git/repositories/root/test.git/hooks/post-receive is not executable
<p>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 <code>doctor.log</code> file in the directory from which it runs. Or it can be displayed on the standard output with <code>--log-file -</code>, which is most convenient when running in docker.</p>
<h3 id="going-further">Going further<a class="zola-anchor" href="#going-further" aria-label="Anchor link for: going-further"
<p>If that was helpful to you, I would very much appreciate if you <a href="https://mastodon.online/@dachary">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 <a href="https://github.com/go-gitea/gitea/pulls">send a pull request</a> to improve the doctor and help it mature.</p>