gitlab-org--gitlab-foss/doc/administration/repository_storage_paths.md

stage	group	info	type
Create	Gitaly	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	reference, howto

Repository storage paths

Introduced in GitLab 8.10.

GitLab allows you to define multiple repository storage paths (sometimes called storage shards) to distribute the storage load between several mount points.

Notes:

• You must have at least one storage path called default.
• The paths are defined in key-value pairs. The key is an arbitrary name you can pick to name the file path.
• The target directories and any of its sub-paths must not be a symlink.
• No target directory may be a sub-directory of another; no nesting.

Example: this is OK:

default:
  path: /mnt/git-storage-1
storage2:
  path: /mnt/git-storage-2

This is not OK because it nests storage paths:

default:
  path: /mnt/git-storage-1
storage2:
  path: /mnt/git-storage-1/git-storage-2 # <- NOT OK because of nesting

Configure GitLab

For backups to work correctly, the storage path cannot be a mount point, and the GitLab user must have correct permissions for the parent directory of the path. Omnibus GitLab takes care of these issues for you, but for source installations you should be extra careful.

The thing is that for compatibility reasons gitlab.yml has a different structure than Omnibus. In gitlab.yml you indicate the path for the repositories, for example /home/git/repositories, while in Omnibus you indicate git_data_dirs, which for the example above would be /home/git. Then, Omnibus creates a repositories directory under that path to use with gitlab.yml.

WARNING: This detail matters because while restoring a backup, the current contents of /home/git/repositories are moved to /home/git/repositories.old. If /home/git/repositories is the mount point, then mv would be moving things between mount points, and bad things could happen. Ideally, /home/git would be the mount point, so things would remain inside the same mount point. Omnibus installations guarantee this, because they don't specify the full repository path but instead the parent path, but source installations do not.

Next, edit the configuration files, and add the full paths of the alternative repository storage paths. In the example below, we add two more mount points that are named nfs_1 and nfs_2 respectively.

NOTE: This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. Read the relevant documentation for more details.

For installations from source

1. Edit gitlab.yml and add the storage paths:

   repositories:
     # Paths where repositories can be stored. Give the canonicalized absolute pathname.
     # NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
     storages: # You must have at least a 'default' storage path.
       default:
         path: /home/git/repositories
       nfs_1:
         path: /mnt/nfs1/repositories
       nfs_2:
         path: /mnt/nfs2/repositories
   

2. Restart GitLab for the changes to take effect.

NOTE: We plan to replace gitlab_shell: repos_path entry in gitlab.yml with repositories: storages. If you are upgrading from a version prior to 8.10, make sure to add the configuration as described in the step above. After you make the changes and confirm they are working, you can remove the repos_path line.

For Omnibus installations

1. Edit /etc/gitlab/gitlab.rb by appending the rest of the paths to the default one:

   git_data_dirs({
     "default" => { "path" => "/var/opt/gitlab/git-data" },
     "nfs_1" => { "path" => "/mnt/nfs1/git-data" },
     "nfs_2" => { "path" => "/mnt/nfs2/git-data" }
   })
   

   Note that Omnibus stores the repositories in a repositories subdirectory of the git-data directory.

Choose where new repositories are stored

After you set the multiple storage paths, you can choose where new repositories are stored in the Admin Area under Settings > Repository > Repository storage > Storage nodes for new repositories.

Each storage can be assigned a weight from 0-100. When a new project is created, these weights are used to determine the storage location the repository is created on.

Beginning with GitLab 8.13.4, multiple paths can be chosen. New repositories are randomly placed on one of the selected paths.

Move a repository to a different repository path

To move a repository to a different repository path, use the Project repository storage moves API. Use the same process as migrating existing repositories to Gitaly Cluster.