GitLab LFS setup

Recently I was playing around with GitLab LFS setup, although the documentation on GitLab website has most of the technical background however there are a few details and examples missing. I’ll complement some of them here.

The official documentation is located here:

My setup is: Omnibus GitLab + Google Cloud Storage (GCS) bucket.

Step 1

You’ll need to setup a GCP project and a service account with a particular bucket’s admin permission assigned. Download the json and upload it to GitLab instance. Let’s assume it is located at /etc/gitlab/gcs.json

Gotcha 1: when file permission is 600 with root:root u/g, gitlab will not be able to read the key. It needs to be set as git:git u/g, or 644 permission (not safe). This is not specified in GitLab documentation.

Step 2

Setup LFS server configuration in gitlab.rb

Gotcha 2: No full example of how things should be setup. Here is my working setup example related to LFS:

gitlab_rails['lfs_enabled'] = true
gitlab_rails['lfs_object_store_enabled'] = true # Optional, default to false
gitlab_rails['lfs_object_store_direct_upload'] = true # Optional, default to false
gitlab_rails['lfs_object_store_remote_directory'] = 'bucket-name'
gitlab_rails['lfs_object_store_proxy_download'] = true
gitlab_rails['lfs_object_store_connection'] = {
  'provider' => 'Google',
  'google_project' => 'gcp_project_name',
  'google_client_email' => '',
  'google_json_key_location' => '/etc/gitlab/gcs.json'

Obviously you need to reconfigure gitlab after applying such configuration.

Step 3

Setup a LFS enabled repo and test.

Setting up a LFS repo is pretty straightforward, there are plenty of tutorials available online. Let’s assume that the LFS files are not being referenced at all in other GitLab projects.

Step 4

LFS object removal

This is the most head-aching part of GitLab, according to this issue, this is still work-in-progress, however the function is actually already implemented in GitLab.

Gotcha 3: Assume project deletion, all LFS files are no longer referenced anymore and when you see GCS you still see the files there occupying the space. GitLab actually removes LFS remote files as a cron job, the detail is not documented. In your https://git/admin/background_jobs page select Cron, there is a background job called remove_unreferenced_lfs_objects_worker which you can manually trigger in order to remove LFS remote files immediately, or just wait until the next cron execution.

Leave a comment

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.