Connect your version control system#

To use Build Automation with your projects, you must first host your project in a source control system (also known as a version control system). Unity Build Automation supports:

• Unity Version Control
• Git
• Azure
• SVN
• Perforce

The following shows you how to set up source control for Build Automation.

Connect Build Automation to Unity Version Control#

Unity Build Automation supports projects stored in UVCS repositories.

1. From the Build settings, select the Source control tab.
2. From the drop-down, select UVCS.
3. In the source control provider URL field, add the URL to your UVCS cloud server or select from the list of available organizations.
4. Select Authenticate with Unity ID, or Authenticate with username or password.
5. If you select Authenticate with username or password, enter the Username and Password for your UVCS server.
6. Select an Authentication Type from the dropdown.
7. If your repository is encrypted, check the My repository is encrypted box. a. Add the Encryption key. b. Add the Encryption method.
8. Select Save.

Connect Build Automation to Git#

Unity Build Automation supports projects stored in Git repositories. Your repository can be hosted on GitHub, GitLab, Bitbucket, or private servers.

You can configure access to your repository using the following authorization protocols:

• Personal Access Tokens (default)
• SSH keys

You can also choose which Git Executable your build will use if you are using a Windows operating system.

Personal Access Tokens#

To configure Build Automation to use a Personal Access Token to access your repository:

1. From the Build settings, select the Source control tab.
2. From the drop-down, select GitHub, Bitbucket, or GitLab.
3. Generate a Personal Access Token from your Git provider.
4. Enter your token and select Authorize so Unity can access your provider account.
5. Select your preferred repository from the drop down.
6. From the Build settings page, select Save.

Personal Access Tokens vary by provider. Relevant details for each provider are included below, but please refer to your provider's documentation for up to date details on how to generate and use your token.

GitHub#

Build Automation requires read access to the repository you wish to build.

If you are using a Personal Access Token (classic) then the specific permissions required are repo if the repository you intend to build is private, or public_repo if the repo you intend to build is public and you want to allow the minimum level of access.

If you plan to enable auto-build in Build Automation, then the write:repo_hook permission is also required.

GitHub automatically removes classic Personal Access Tokens that haven't been used in a year, even if you did not provide an expiration date when creating the token.

Fine-grained Personal Access Tokens can be created for a user or an organization. Access can be granted to all repositories owned by the user or organization, or only to specific repositories. If you choose to use Fine-grained tokens, and you are not configuring a token with only Public Repositories access, you will have to add specific permissions to the access token.

The following Repository Permissions are the minimum required to use a Fine-grained token:

• Contents Read-only
• Webhooks Read and write (if auto-build is used)

Build Automation does not require any Account Permissions.

Note that Fine-grained Personal Access Tokens always have an expiration date, once a token has expired Build Automation will no longer be able to access your repository.

GitLab#

Personal Access Tokens must be granted the read_repository scope in order for Build Automation to build your repository. If you intend to enable auto-build, If you plan to enable auto-build in Build Automation, then the write_repository scope is also required.

GitLab tokens are always created with an expiration date, once a token has expired Build Automation will no longer be able to access your repository.

Bitbucket#

Repository Access Tokens grant access to a single repository, so you'll have to create a token for each repository you wish to build.

Tokens must be granted Read permissions on the Repositories scope in order for Build Automation to build your repository. If you plan to enable auto-build in Build Automation, then you will also need to grant Read and write on the Webhooks scope.

For all providers, Build Automation will no longer be able to access your repository if you revoke the access token, if your token expires, or if the user associated with the token has their access to the repository reduced or revoked.

For the next step, see Setting up a target build platform.

SSH keys and private repositories#

When Build Automation connects to the hosting site, it automatically detects whether your repository is public or private. If your repository is public, Build Automation automatically connects to it, and you can skip to Build Configuration.

If your repository is private an SSH key is generated and displayed in the settings screen below the repository URL. Add this SSH key to the settings of your source control provider to grant Build Automation access.

To configure Build Automation to use an SSH key to access your repository:

1. In the Source control tab, from the drop-down > Manual setup, select Git.
2. In the Source control provider URL field, add the URL to your Git server. The following are examples of URLs for GitHub, Bitbucket, and GitLab:
   • git@github.com:youraccount/yourrepo.git
   • git@bitbucket.org:youraccount/yourrepo.git
   • git@gitlab.com:youracccount/yourrepo.git
3. Add the SSH key to your source control provider settings if the repository is private.
4. Once the setup is complete, on the Source control tab, select Save.

Connect Build Automation to Azure#

Unity Build Automation supports projects stored in Azure repositories.

Configuring Azure on the Dashboard#

1. From the Build settings page, select the Source control tab.
2. From the drop-down, select Azure.
3. Add your Azure Organization.
4. Add the Azure Project that the code repository belongs to.
5. Create and provide your Azure Personal Access Token.
6. Select Authorize to allow Unity to retrieve your repositories.
7. Select Save.

Connect Build Automation to SVN#

Unity Build Automation supports projects hosted in Apache Subversion (SVN) repositories.

1. From the Build settings page, select the Source control tab.
2. From the drop-down > Manual setup, then select SVN.
3. In your SVN server, create a read-only user account just for Unity Build Automation, along with a secure password.
4. From the Build settings page, enter the new username and password in the fields.
5. Select Save.

Public SSH Keys

Build Automation does not support connecting to your SVN repository using a public SSH Key. Use a username and password instead.

SSL Certificates

Self-signed SSL certificates are not supported. Build Automation does not support an SSL handshake with a server with a self-signed certificate. The hostname in the certificate must match the hostname accessed by Build Automation.

Connect Build Automation to Perforce#

Unity Build Automation supports Projects stored in Perforce repositories.

Configuring Perforce on the Dashboard#

1. From the Build settings page, select the Source control tab.
2. From the drop-down > Manual setup, then select Perforce.
3. In the source control provider URL field, enter the URL of your Perforce server. You can specify the URL to use the https:// or SSL protocols. The following are examples of valid URLs:
   • https://127.0.0.1:1667
   • ssl:127.0.0.1:167
4. In P4, create a user with read-only access to your repository.
5. From the Build settings page, enter the username and password in the fields.
6. Select Save.

Next steps#

• Create your first build configuration.
• Run your first build.