How to use GitHub on a Unity project

If you're new to version control and have only ever heard of "GitHub" or "Git" in the context of collaborating on a Unity project or backing up files, read on. This guide will explain how to upload a Unity project on GitHub and how to use if for personal and team projects.

In this guide, you'll learn:

• What Git and GitHub are
• How to upload your Unity project to GitHub
• Why version control is extremely important
• A recommended workflow for Unity projects
• The next steps

What is Git and what is GitHub?

GitHub is one of the most popular cloud services, based on the Git version control system, and comes with several additional features that can help you manage and automate tasks. To access the GitHub cloud service, you can use Git version control commands or, much simpler, a desktop application that pushes and pulls files to GitHub like Anchorpoint, Fork or SourceTree.

Prerequisites

To push your Unity project files to GitHub, you need:

• A GitHub account
• A desktop application (a Git client) that tracks your files, filters unnecessary ones and uploads only the changed files to GitHub. This can be done by Anchorpoint, SourceTree or GitHub Desktop
• A Unity plugin (not mandatory) that allows you to push files directly from the Unity Editor

How to upload a Unity project to GitHub

Setting up GitHub for Unity is actually pretty easy and involves just a few steps. These are the components that we will use:

• An existing Unity project
• GitHub (for hosting our Unity files)
• Anchorpoint (Our application that will push and pull our files to GitHub)

Configure Unity

You can use an existing Unity project. If you are using Unity 2021 or newer, you don’t need to do any configuration. But just to double-check, make sure that asset serialization is set to force text and that meta files are set to visible. To do that, go to Edit / Project Settings / Editor and make sure that under Asset Serialization the mode is set to "Force Text".

Setting up GitHub

Setting up GitHub requires just a few clicks. Go to GitHub.com and create a free account.

Setting up your Git desktop application

In this case, we will use Anchorpoint but you can also use any other Git client. If you use another Git client, you have to create the repository on GitHub and then copy the remote URL to your Git client. In Anchorpoint, we will use the GitHub integration. Download and install Anchorpoint and create an account.

You must authorise both 'Anchorpoint Software' and 'Git Ecosystem'. This gives Anchorpoint permission to create GitHub repositories in your account on your behalf. The final step is to test your integration, after which you should be ready to go.

If everything is fine, it should be marked as "Connected". You can close this popup now.

Create a new Git repository on GitHub from Anchorpoint

A repository is like a project, basically the folder that contains your Unity files.

Browse to the place where your Unity project is located. In the Remote Settings pick "New GitHub Repository" and for the Template for .gitignore pick "Unity". Then press "Continue". In the next steps you will be asked if you want to add collaborators. We can do that later.

What is a .gitignore?

In Unity projects, a ".gitignore" file prevents Git from tracking files like "Library/, Temp/, Build/" and other generated or platform-specific folders. This keeps the repository clean and avoids syncing large, unnecessary files that Unity can regenerate anyway.

Once you have the project (or repository) ready, you can upload your Unity project. Anchorpoint calls that step "Sync" which is basically a chain of 3 Git commands (add, commit and push). We will explain that later.

That's it, now you have uploaded your Unity project on GitHub and are ready to use version control.

Using the Unity plugin

If you want to commit directly from Unity and see the file status directly in your editor, you can also use the Anchorpoint Git plugin for Unity. In Unity:

1. Go to Window / Package Manager
2. Click on the "+" icon in the top left corner and pick "Add package from git URL..."
3. Copy and paste this URL https://github.com/Anchorpoint-Software/ap-unity.git

This will tell Unity to download the plugin as a package. Watch the video below to see how to use the plugin in your Unity projects.

Workflow and project setup recommendations

You want to make daily committing a habit in your workflow. You make a significant change (e.g., you created a new version of your character or implemented a major change to a game mechanic), then you want to commit it. Git commits are fast because they happen locally. When the commit is complete, you can keep working, and all your files are pushed to GitHub in the background.

Your average day looks like this

1. You do your work in Unity.
2. You open the Timeline in Anchorpoint, add a comment, and press Sync.
3. To get your changes, your team member has to Pull them.
4. Your team member does their work in Unity.
5. Your team member comments on their work and presses Push as well.

File locking

You should use file locking on binary files, prefabs, and Unity scenes, because if you make a lot of edits to these types of assets, it can sometimes be difficult to merge and resolve conflicts.  

Prefabs, folder structure and naming conventions

A good approach to developing games in Unity is to split your work into prefabs to avoid conflicts, along with a proper folder structure and naming convention to avoid renaming as much as possible.

Branching

Keep it to a minimum. The basics should be a development branch and a release branch. Work on development, and merge to your release branch from time to time. If you want to dig deeper, take a look at the concept of "trunk based development", which explains a proper branching strategy for game development. A practice where you work on the main branch, but create short feature branches that merge back into the main branch every day.

A proper Git configuration

When using Anchorpoint, you normally don’t need to deal with these things, but if you use another desktop application such as SourceTree or GitHub desktop, you have to make sure that:

1. Your .gitignore file is set up correctly. This is a configuration, so that we avoid uploading cache files such as “Library”, “Logs” or “Builds”
2. Git LFS is installed and configured. This is an extension that needs to be enabled, so that Git can handle large binary files properly

Going back if something breaks

Git has several options for restoring, reverting to previous versions of files in your repository, and even restoring the project to a specific commit state.

You can undo all file changes from a commit if you didn't change any files. You can revert files to the last state saved in the repository, or even revert the entire project back to a specific commit.

CI/CD build pipeline for Unity

Continuous integration and continuous deployment (CI/CD) are DevOps practices that help teams efficiently develop and release high-quality software. Within the Unity environment, CI/CD can automate various tasks, such as running tests across multiple builds or deploying to multiple platforms with a single action.

Implementing a simple pipeline can help identify bugs early in development and automatically generate and deploy builds for team leads to review and QA to test, whether on every commit, daily, or weekly. This streamlines production, minimizes overhead for team members, and allows them to focus on their core tasks, such as coding, art, or design. Read our guide on setting up a CI/CD build pipeline for Unity using GitHub Actions to learn more.

GitHub limitations

GitHub has some limitations when it comes to storage that can be an issue for game development. If you reach these limitations, a push will be rejected in Anchorpoint and you will get an error message. If these are an issue for your project, you may want to look to other solutions such as Azure DevOps or self-host your Git server using Gitea.

Individual file size limitations

The free version of GitHub limits file sizes up to 2GB. If you are on a paid plan, this limitation increases to 4GB.

Repository limitations

With the free plan, you get 1 GB of storage. With Git LFS activated, you get 10 GB of storage and bandwidth for your repository. If you exceed these limits, you will need to pay $0.0875/GB for bandwidth and $0.07/GB for extra storage.

Frequently asked questions

Why do I need version control? Isn't Dropbox enough?

A Dropbox is likely to damage your project. If you have the Unity project open in a Dropbox on multiple computers (which is exactly what happens when you work in a team), Dropbox will sync files instantly. If you are working on the file (say a .unity scene) and your team member is also working on it, this will cause a conflict that Dropbox will resolve by renaming the file. This becomes a nightmare to sort out. Also, WIP scripts that are changed due to file syncing will make it impossible to launch your game.

Version control can sync files as well, but as the name says, with more control. It allows you to:

• To do backups for your project, in case your files get corrupted
• To sync between computers
• To share your files with your team
• It forces you to work in a proper way by committing your work at least once a day
• Adds documentation to your work
• It facilitates team collaboration with features such as file locking, so that you prevent losing work due to the fact that two people have worked on the same file at the same time

Setting up a version control solution takes only a few minutes. It's definitely one of the first things you do when you start a new Unity project. Similar to file synchronization, there are several solutions available.

Does GitHub provide an official Unity plugin?

There is (better said was) an official Git plugin for Unity from GitHub but it's deperecate since 2024. Here is the original code repository.

Is Unity Collaborate still a thing?

No, similar to the official GitHub plugin for Unity, Unity Collaborate got deprecated as well.

Can I use it for free?

Git has the biggest ecosystem, so there are plenty of possibilities. GitHub offers a free tier with unlimited users and 1 GB of storage. It also provides a free Git LFS plan with 10 GB of storage and bandwidth and a maximum file size limit of 2 GB. Another option is Azure DevOps, which is free for five users with unlimited storage.

What is Git in more detail?

Git is a version control solution that was developed for building the Linux kernel and was initially released in 2005. Git is a decentralized version control system. This means that you have a copy of the whole repository on your computer. A repository is basically your Unity project folder on a remote server, e.g., GitHub.

The benefit of working decentralized means that you can fully work offline, you have an automated backup system, and file operations are way faster because you don’t need to wait for a server. To sync with your team, you push (upload) your files to the remote repository, and you pull (download) new file changes from the repository to your local computer. These steps are done manually, in contrast to Dropbox, which is syncing files instantly.

What is Git LFS?

Git was made to deal with code, which is basically a bunch of text files. Games require a lot of binary files like 3D models, textures, sound files, etc. To keep the efficiency and to not download the whole history of your 3D models and textures, Git introduced an add-on in 2014 called Git LFS (Large File Storage). This add-on is now part of almost every Git product and service out there.

It helps to deal with binary files by storing them in a separate location on the remote server and replacing the original file with a 1kb sized pointer. This pointer only knows where the original file is so it can be downloaded to your local computer on demand. This allows you to save storage space.

When you decide on a Git hosting provider (GitHub, GitLab, Bitbucket, or Azure DevOps), you have to look at their Git LFS costs.

Why do I need a .gitignore file?

Unity produces a lot of overhead of files that store caches, build data, or anything else that you don’t want to upload to the Git repository. It will just take away space and slow down your push and pull procedures.

A .gitignore file is basically a filter that tells Git which files, file types, and folders should never be committed to the Git version history. Here is an example gitignore for Unity.

How does branching work?

When a project becomes more complex or the team gets bigger, friction arises. Work in progress commits from e.g. developers can disturb the work of the artist. To prevent this, you can split the project into certain zones. Each zone can then be used by a developer or artist without getting in each other’s way. When the work is finished, these zones are dissolved and merged into the project. Git calls such things branches. A short video in our documentation explains them pretty well.

The recommendation is to keep the number of branches very small. The reason is, when you work on your own branch for a long time, you may never run into conflicts. But, once you merge that branch to the main line (imagine this like a giant commit), all conflicts that you ignored have to be solved now. It’s better to run into conflicts early and solve them quickly by working only on one branch.

If you need branches, Anchorpoint allows you to create and switch them in the dropdown in the Timeline next to the Pull button.

Are there good alternatives to GitHub?

GitHub can work great if your project size is pretty small. As soon as you are in the double-digit gigabyte range, it’s smarter to pick another Git hosting provider such as Azure DevOps or self-host your Git server. We made a comparison in 2022 so you don’t need to spend so much time on research.