9.7 KiB
GitLab Git LFS Administration
Documentation on how to use Git LFS are under Managing large binary files with Git LFS doc.
Requirements
- Git LFS is supported in GitLab starting with version 8.2.
- Support for object storage, such as AWS S3, was introduced in 10.0.
- Users need to install Git LFS client version 1.0.1 and up.
Configuration
Git LFS objects can be large in size. By default, they are stored on the server GitLab is installed on.
There are various configuration options to help GitLab server administrators:
- Enabling/disabling Git LFS support
- Changing the location of LFS object storage
- Setting up object storage supported by Fog
Configuration for Omnibus installations
In /etc/gitlab/gitlab.rb
:
# Change to true to enable lfs - enabled by default if not defined
gitlab_rails['lfs_enabled'] = false
# Optionally, change the storage path location. Defaults to
# `#{gitlab_rails['shared_path']}/lfs-objects`. Which evaluates to
# `/var/opt/gitlab/gitlab-rails/shared/lfs-objects` by default.
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
Configuration for installations from source
In config/gitlab.yml
:
# Change to true to enable lfs
lfs:
enabled: false
storage_path: /mnt/storage/lfs-objects
Storing LFS objects in remote object storage
Introduced in GitLab Premium 10.0. Brought to GitLab Core in 10.7.
It is possible to store LFS objects in remote object storage which allows you
to offload local hard disk R/W operations, and free up disk space significantly.
GitLab is tightly integrated with Fog
, so you can refer to its documentation
to check which storage services can be integrated with GitLab.
You can also use external object storage in a private local network. For example,
Minio is a standalone object storage service, is easy to setup, and works well with GitLab instances.
GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload".
Option 1. Direct upload
- User pushes an lfs file to the GitLab instance
- GitLab-workhorse uploads the file directly to the external object storage
- GitLab-workhorse notifies GitLab-rails that the upload process is complete
Option 2. Background upload
- User pushes an lfs file to the GitLab instance
- GitLab-rails stores the file in the local file storage
- GitLab-rails then uploads the file to the external object storage asynchronously
The following general settings are supported.
Setting | Description | Default |
---|---|---|
enabled |
Enable/disable object storage | false |
remote_directory |
The bucket name where LFS objects will be stored | |
direct_upload |
Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | false |
background_upload |
Set to false to disable automatic upload. Option may be removed once upload is direct to S3 | true |
proxy_download |
Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | false |
connection |
Various connection options described below |
The connection
settings match those provided by Fog.
Here is a configuration example with S3.
Setting | Description | example |
---|---|---|
provider |
The provider name | AWS |
aws_access_key_id |
AWS credentials, or compatible | ABC123DEF456 |
aws_secret_access_key |
AWS credentials, or compatible | ABC123DEF456ABC123DEF456ABC123DEF456 |
aws_signature_version |
AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 |
region |
AWS region | us-east-1 |
host |
S3 compatible host for when not using AWS, e.g. localhost or storage.example.com |
s3.amazonaws.com |
endpoint |
Can be used when configuring an S3 compatible service such as Minio, by entering a URL such as http://127.0.0.1:9000 |
(optional) |
path_style |
Set to true to use host/bucket_name/object style paths instead of bucket_name.host/object . Leave as false for AWS S3 |
false |
Here is a configuration example with GCS.
Setting | Description | example |
---|---|---|
provider |
The provider name | Google |
google_project |
GCP project name | gcp-project-12345 |
google_client_email |
The email address of the service account | foo@gcp-project-12345.iam.gserviceaccount.com |
google_json_key_location |
The json key path | /path/to/gcp-project-12345-abcde.json |
NOTE: The service account must have permission to access the bucket. See more
Manual uploading to an object storage
There are two ways to manually do the same thing as automatic uploading (described above).
Option 1: rake task
$ rake gitlab:lfs:migrate
Option 2: rails console
$ sudo gitlab-rails console # Login to rails console
> # Upload LFS files manually
> LfsObject.where(file_store: [nil, 1]).find_each do |lfs_object|
> lfs_object.file.migrate!(ObjectStorage::Store::REMOTE) if lfs_object.file.file.exists?
> end
S3 for Omnibus installations
On Omnibus installations, the settings are prefixed by lfs_object_store_
:
-
Edit
/etc/gitlab/gitlab.rb
and add the following lines by replacing with the values you want:gitlab_rails['lfs_object_store_enabled'] = true gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects" gitlab_rails['lfs_object_store_connection'] = { 'provider' => 'AWS', 'region' => 'eu-central-1', 'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N', 'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE', # The below options configure an S3 compatible host instead of AWS 'host' => 'localhost', 'endpoint' => 'http://127.0.0.1:9000', 'path_style' => true }
-
Save the file and reconfigure GitLabs for the changes to take effect.
-
Migrate any existing local LFS objects to the object storage:
gitlab-rake gitlab:lfs:migrate
This will migrate existing LFS objects to object storage. New LFS objects will be forwarded to object storage unless
gitlab_rails['lfs_object_store_background_upload']
is set to false.
S3 for installations from source
For source installations the settings are nested under lfs:
and then
object_store:
:
-
Edit
/home/git/gitlab/config/gitlab.yml
and add or amend the following lines:lfs: enabled: true object_store: enabled: false remote_directory: lfs-objects # Bucket name connection: provider: AWS aws_access_key_id: 1ABCD2EFGHI34JKLM567N aws_secret_access_key: abcdefhijklmnopQRSTUVwxyz0123456789ABCDE region: eu-central-1 # Use the following options to configure an AWS compatible host such as Minio host: 'localhost' endpoint: 'http://127.0.0.1:9000' path_style: true
-
Save the file and restart GitLab for the changes to take effect.
-
Migrate any existing local LFS objects to the object storage:
sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
This will migrate existing LFS objects to object storage. New LFS objects will be forwarded to object storage unless
background_upload
is set to false.
Storage statistics
You can see the total storage used for LFS objects on groups and projects in the administration area, as well as through the groups and projects APIs.
Troubleshooting: Google::Apis::TransmissionError: execution expired
If LFS integration is configred with Google Cloud Storage and background uploads (background_upload: true
and direct_upload: false
),
sidekiq workers may encouter this error. This is because the uploading timed out with very large files.
LFS files up to 6Gb can be uploaded without any extra steps, otherwise you need to use the following workaround.
$ sudo gitlab-rails console # Login to rails console
> # Set up timeouts. 20 minutes is enough to upload 30GB LFS files.
> # These settings are only in effect for the same session, i.e. they are not effective for sidekiq workers.
> ::Google::Apis::ClientOptions.default.open_timeout_sec = 1200
> ::Google::Apis::ClientOptions.default.read_timeout_sec = 1200
> ::Google::Apis::ClientOptions.default.send_timeout_sec = 1200
> # Upload LFS files manually. This process does not use sidekiq at all.
> LfsObject.where(file_store: [nil, 1]).find_each do |lfs_object|
> lfs_object.file.migrate!(ObjectStorage::Store::REMOTE) if lfs_object.file.file.exists?
> end
See more information in !19581
Known limitations
- Support for removing unreferenced LFS objects was added in 8.14 onwards.
- LFS authentications via SSH was added with GitLab 8.12
- Only compatible with the GitLFS client versions 1.1.0 and up, or 1.0.2.
- The storage statistics currently count each LFS object multiple times for every project linking to it