Check a project’s repository using GitLab UI
Enable repository checks for all projects
Run a check using the command line
What to do if a check failed
Repository checks
You can use
git fsck
to verify the integrity of all data
committed to a repository. GitLab administrators can:
Check a project’s repository using GitLab UI
To check a project’s repository using GitLab UI:
-
On the top bar, select
Main menu > Admin
.
-
On the left sidebar, select
Overview > Projects
.
-
Select the project to check.
-
In the
Repository check
section, select
Trigger repository check
.
The checks run asynchronously so it may take a few minutes before the check result is visible on the
project page in the Admin Area. If the checks fail, see
what to do
.
Enable repository checks for all projects
Instead of checking repositories manually, GitLab can be configured to run the checks periodically:
-
On the top bar, select
Main menu > Admin
.
-
On the left sidebar, select
Settings > Repository
(
/admin/application_settings/repository
).
-
Expand the
Repository maintenance
section.
-
Enable
Enable repository checks
.
When enabled, GitLab periodically runs a repository check on all project repositories and wiki
repositories to detect possible data corruption. A project is checked no more than once per month.
Administrators can configure the frequency of repository checks. To edit the frequency:
If any projects fail their repository checks, all GitLab administrators receive an email
notification of the situation. By default, this notification is sent out once a week at midnight at
the start of Sunday.
Repositories with known check failures can be found at
/admin/projects?last_repository_check_failed=1
.
You can run
git fsck
using the command line on repositories on
Gitaly servers
. To locate the repositories:
-
Go to the storage location for repositories:
-
For Omnibus GitLab installations, repositories are stored in the
/var/opt/gitlab/git-data/repositories
directory
by default.
-
For GitLab Helm chart installations, repositories are stored in the
/home/git/repositories
directory inside the
Gitaly pod by default.
-
Identify the subdirectory that contains the repository
that you need to check.
-
Run the check. For example:
sudo -u git /opt/gitlab/embedded/bin/git \
-C /var/opt/gitlab/git-data/repositories/@hashed/0b/91/0b91...f9.git fsck --no-dangling
The error
fatal: detected dubious ownership in repository
means you’re running the command
using the wrong account. For example,
root
.
What to do if a check failed
If a repository check fails, locate the error in the
repocheck.log
file
on disk at:
/var/log/gitlab/gitlab-rails
for Omnibus GitLab installations.
-
/home/git/gitlab/log
for installations from source.
-
/var/log/gitlab
in the Sidekiq pod for GitLab Helm chart installations.
If periodic repository checks cause false alarms, you can clear all repository check states:
-
On the top bar, select
Main menu > Admin
.
-
On the left sidebar, select
Settings > Repository
(
/admin/application_settings/repository
).
-
Expand the
Repository maintenance
section.
-
Select
Clear all repository checks
.
Error:
failed to parse commit <commit SHA> from object database for commit-graph
You can see a
failed to parse commit <commit SHA> from object database for commit-graph
error in repository check logs. This error occurs if your
commit-graph
cache is out
of date. The
commit-graph
cache is an auxiliary cache and is not required for regular Git operations.
While the message can be safely ignored, see the issue
error: Could not read from object database for commit-graph
for more details.
Dangling commit, tag, or blob messages
Repository check output often includes tags, blobs, and commits that must be pruned:
This is common in Git repositories. They’re generated by operations like
force pushing to branches, because this generates a commit in the repository
that is not longer referred to by a ref or by another commit.
If a repository check fails, the output is likely to include these warnings.
Ignore these messages, and identify the root cause of the repository check failure
from the other output.
GitLab 15.8 and later
no
longer includes these messages in the check output. Use the
--no-dangling
option
to suppress then when run from the command line.