Search Unity

Git LFS Support in Cloud Build

October 10, 2017 in Technology | 4 min. read

Cloud Build for Unity Teams is a continuous integration service for games and apps built in Unity. Cloud Build makes it simple and easy to create and share builds of your game, letting you and your team iterate faster and always be on the same page. Setting up Cloud Build takes seconds and works with your existing source control repository.

Cloud Build now supports Large File Storage in Git source control repos, also known as Git LFS for short.  So now, you can create larger builds with Cloud Build when using it with Git!  Read on to learn more.

What is Git LFS?

Git Large File Storage (LFS) is a technology that allows providers to keep large assets/files outside of a Git repository, keeping total filesize down while still maintaining important base assets alongside the project. When a file is added to a traditional Git repository, Git maintains a separate copy of every version of that file. This is great for files containing code, or very small binary/image files. However, this becomes a problem with large files, and providers may warn or prevent you from uploading your changes. Git LFS allows providers and users alike to maintain leaner repositories.

How do I use Git LFS with Cloud Build?

There are no special steps for Cloud Build to recognize LFS; it just works!  As with all Cloud Build projects using git, simply add the SSH key provided in your project’s Source Control Settings area to a user on GitHub with access to the repo. Cloud Build will recognize the need to use LFS and download your files accordingly before a build begins. Need a walkthrough? Check out this video, showing how to setup Cloud Build.

How does Git LFS work?

The Git LFS client is a command line utility that sits next to the existing git command line executable and interoperates with it. It allows a developer to track certain files within their repository, which marks them for management by the LFS subsystem. These files are replaced with text-based pointer files in the repository, and the files they represent are uploaded and stored separately outside of the repository. Upon checkout, Cloud Build uses the Git LFS client to determine where these files are and pull them down before your build.

How do I use Git LFS?

Download and installation instructions for Git end users can be found on the Git LFS website, and can be used with any Git-based source control where LFS has been implemented. Once installed, the git lfs track command is used to specify which files should be handled by the LFS system:

$ git lfs track "**/*.wav"

This example command will generate or add to a .gitattributes file, specifying that all WAV files should be tracked by LFS. That’s it! All WAV files will be managed via Git LFS. Additional file names or wildcards can be specified with the git lfs track command. Note: Please be sure to include the .gitattributes file when you commit changes.

Git LFS Provider Support

GitHub is the source of the Git LFS project, and as such is the most prominent server implementation at this time. There are other services that also offer Git LFS support, however they do not currently support using LFS with SSH keys. In order to use a Git LFS host with Unity Cloud Build, they must allow authorization for it via SSH. Some other notes should be taken into consideration:

  • GitHub deployment keys are not supported: SSH keys are handled in various ways within GitHub, and usage of LFS via deployment key is not currently supported. An alternative approach is the use of machine users, or separate user accounts that the SSH key can be used with.
  • Bandwidth and storage are likely measured: Git LFS is a bandwidth and storage intensive service, and as such, there are likely charges associated with both when heavily utilizing it. In GitHub’s case, free usage is capped at 1GB per month for bandwidth and 1GB of storage. In addition to any caps, it’s important to take any additional hosting costs into account.


In conclusion, Git LFS is a great option to consider when utilizing Git as your method of source control while using Unity and Unity’s services. If using Git LFS seems complicated, but your project works with large files, try out Collaborate for Unity Teams.  It handles large files without any extra effort, and setting it up to work with Cloud Build is super simple.  No bandwidth limits to worry about either; just storage.

The Cloud Build team works hard to support the needs of Unity developers that wish to take advantage of continuous integration in their development pipelines. We look forward to improving the service even more as time goes on. Happy building!

Cloud Build is built right into Unity. Click here to get started!

October 10, 2017 in Technology | 4 min. read