Plugin for TeamCity

Integrate TeamCity with Unity Version Control for your CI/CD pipeline.

Read time 6 minutes

Last updated 21 days ago

Installation

The Unity Version Control (UVCS) plugin for TeamCity extends the capabilities of the TeamCity server, enabling it to manage continuous integration operations using source data that is under UVCS control. To install the UVCS plugin for TeamCity:

Open "Plugins list" from TeamCity's Administration menu.
Click the "Upload plugin zip" link.
Changing the user identity
Upload the UVCS plugin for TeamCity:


<UVCS installation directory>/client/plugins/teamcity/com.codicesoftware.plugins.teamcity.PlasticSCM.zip

Restart TeamCity Server. This way, the plugin will be automatically unpacked and loaded.
(Windows systems only) The plug-in runs UVCS commands with the user identity of the TeamCity Build Agent Service (Agent-side checkout mode). By default, this identity is the SYSTEM user account. We recommend changing this service's user account to a different one:
1. Go to Control Panel > Administrative Tools > Services.
2. Right-click TeamCity Build Agent Service and select Properties.
3. Go to the "Log On" tab and select another user who already has a valid UVCS configuration.
  Changing the user identity
Start the TeamCity Server service.

Configuration

Create a new Project in TeamCity

First step is creating a new Project in TeamCity, which will be attached to UVCS later. To do that, Go to "Administration" > "Projects" and click on "Create new Project" button.

Type a valid Project name, ID and an optional description, and click on "Create" button.

Create a build Configuration

After creating the Project, TeamCity wizard asks for a Build Configuration. Again, enter a valid name, ID and description and click "Create" button.

Configure VCS Root using TeamCity UI

This is the wizard step where we attach our Project to UVCS. Select "Plastic SCM" as a type of VCS, enter a VCS root name and ID, required by TeamCity. The specific fields for UVCS plugin are the following:

Server: location of UVCS server (IP / name:port).
Repository: the UVCS repository to download contents for the build Project.
Branch: the default branch on the specified repository to track changes and build them (/main branch by default).
Branch specification (optional): TeamCity opens the possibility to track other branches' changes different than configured default branch, by entering inclusion / exclusion rules.

(In the example above, all child branches of /main branch will be tracked, excepting those child branches that start with Release string in their name). Click on "Test connection" to check whether the plugin can connect to the configured UVCS server, and if the test connection is successful, on "Create" button.

Configure VCS Root using Kotlin DSL

When using the TeamCity Kotlin DSL to configure your project's VCS Root, you can define parameters to customize the behavior of the UVCS integration. Below is a detailed explanation of the parameters you can use, along with an example configuration.

Supported Parameters

The following parameters are available for configuring VCS Roots:

Parameter name	Description	Example value
`type`	Type of the VCS Root.	`"PlasticSCM"`
`name`	Human-readable name for the VCS Root.	`"My Project VCS Root"`
`server`	UVCS server to connect to.	`"organization@cloud"`
`repository`	Repository name within the UVCS server.	`"Awesome Project"`
`branch`	Default branch to watch.	`/main`
`teamcity:branchSpec`	Branches to monitor besides the default one.	`+:/main/*`
`enable-plastic-branch-filtering`	Enables or disables PlasticSCM branch filtering.	`"true"` , `"false"`
`plastic-branch-filter`	Branch filter query.	`"status=resolved"`
`plastic-branch-filter-attr-failed`	Attribute to mark branches as failed.	`"status=failed"`
`plastic-branch-filter-attr-succeed`	Attribute to mark branches as succeeded.	`"status=tested"`
`plastic-branch-filter-attr-merged`	Attribute to mark branches as merged.	`"status=merged"`

Example Configuration

Below is an example of configuring a VCS Root in Kotlin DSL, utilizing the parameters for branch filtering:


// settings.ktsobject MyProject : VcsRoot({    type = "PlasticSCM"    name = "My Project VCS Root"    param("server", "organization@cloud")    param("repository", "Awesome Project")    // Enable Plastic branch filtering    param("enable-plastic-branch-filtering", "true")    // Define the branch filter query    param("plastic-branch-filter", "status=resolved")    // Define branch attributes for filtering    param("plastic-branch-filter-attr-failed", "status=failed")    param("plastic-branch-filter-attr-succeed", "status=tested")    param("plastic-branch-filter-attr-merged", "status=merged")})

Parameter Details

type

Specifies the type of the VCS Root. For UVCS integrations, this value should always be set to

"PlasticSCM"

to indicate that the VCS Root is using PlasticSCM as the version control system.

name

Defines a human-readable name for the VCS Root configuration. This name is used to identify the VCS Root in the TeamCity UI, and should be unique within your project.

server

Specifies the UVCS server to connect to. This is typically the server name used to access Unity Version Control, such as a cloud organization or an on-premise server.

repository

Defines the name of the repository within the UVCS server. This should match the exact name of the repository you want to connect to.

branch

Defines the name of the default branch to watch within the repository. The default value is

/main

teamcity:branchSpec

Specifies extra branches to monitor as a newline-delimited set of rules in the form of

+:branch-name

-:branch-name

, allowing the wildcard character

. For example,

+:/main/*

would include all child branches of

/main

, while

-:/main/Release*

would exclude those child branches of

/main

that start with "Release" in ther name.

enable-plastic-branch-filtering

This parameter enables or disables branch filtering. If set to "true", the

plastic-branch-filter

parameter will be applied to filter branches.

plastic-branch-filter

Specifies the query used to filter branches. For example, you can use status=resolved to include only branches with the status attribute set to resolved.

plastic-branch-filter-attr-failed

Defines the attribute that marks branches as failed.

plastic-branch-filter-attr-succeed

Specifies the attribute used to mark branches as succeeded.

plastic-branch-filter-attr-merged

Indicates the attribute for marking branches as merged.

Configure checkout from VCS mode

TeamCity supports two different VCS checkout modes to download the contents to be built from UVCS (plus the option to do not perform the VCS checkout automatically, and usually delegating this action to the project's "Build Steps" configuration phase by executing an user-defined script). We highly recommend the "Agent-Side checkout mode", already supported by UVCS TeamCity plugin:

Customize your specific project settings (such as selecting an user-defined checkout directory or VCS labeling on successful build) and when done, click on "Save" button.

Configure build steps

This configuration depends on each specific project in order to trigger a build once the source code at a required version is downloaded.

Configure build trigger

This is the step that rules the way builds are triggered. In this example, we configure a VCS trigger so that builds are launched when TeamCity Server detects new changes in the tracked branches of the specified UVCS repository configured in the previous step: "Configure VCS root for the Project".

Although feature branches are already tracked by TeamCity (as we did in "VCS root" configuration step), we can define which of them will cause TeamCity to trigger a build or not, by setting up a "Branch filter". With the configured branch filter in the example above, any tracked branch will trigger a build when a new change is detected. And that's it, the TeamCity project is ready to watch changes in UVCS repo and start building changes!

A basic build cycle tracking changes from UVCS repo

TeamCity is now ready to track changes from the configured feature branches in a repository. Let's see how TeamCity starts triggering builds when VCS changes are detected through a basic development cycle as an example with an existing repo in a UVCS server. First of all, a developer submits (checks-in in UVCS jargon) new changes in the default tracked branch (in this case, /main branch). A couple of seconds later, TeamCity detects these new changes, checkouts source code from /main branch into the configured workspace folder (from "checkout options" step while configuring the VCS root of the TeamCity project), and starts executing the actions defined in "Build Steps" in order to perform a build:

Now, the same user (

jesus

in this example) creates a child branch in UVCS (/main/scm78453) to perform a couple of changes in order to fix a bug in the code. As the new branch name matches with the "Branch specification" pattern for feature branches to be tracked, TeamCity will trigger a build when detects changes in this new branch:

As the build of the newly created child branch is successful, the integrator decides to merge back to the parent, default /main branch in UVCS. When the merge in the /main branch is checked-in, TeamCity will trigger a build once it's detected. Let's see this new build ("#3") in the Change Log graph, along with the merge link:

The history in the VCS repository continues: a new branch (/main/scm81245) is created, some changes are submitted there, and then, this branch (along with the previous one) is merged into a release branch (/main/Release-792). After that, the release branch /main/Release-792 is also merged back to default /main branch. Let's see how TeamCity triggers new builds for changes in branch /main/scm81245 and /main, but not for the /main/Release-792 branch, as it matches with the configured exclusion pattern in the "Branch specification" defined when configuring the VCS root:

Let's see how the TeamCity's Change Log graph draws these new changes (blue dots) and corresponding builds (green dots).

Documentation

Engine

Services

Grow

Industry

Support

Unity Version Control

DevOps

On-prem

Gluon

Editor plug-in